@vicinae/api 0.16.4 → 0.16.6

package/dist/api/hooks/use-imperative-form-handle.js

@@ -1,11 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useImperativeFormHandle = void 0;
-const crypto_1 = require("crypto");
 const react_1 = require("react");
 const bus_1 = require("../bus");
+const node_crypto_1 = require("node:crypto");
 const useImperativeFormHandle = (ref) => {
-    const handleId = (0, react_1.useRef)((0, crypto_1.randomUUID)());
+    const handleId = (0, react_1.useRef)((0, node_crypto_1.randomUUID)());
     (0, react_1.useImperativeHandle)(ref, () => {
         return {
             focus: () => {

package/dist/api/hooks/use-navigation.d.ts

@@ -1,3 +1,9 @@
+/**
+ * A React hook that lets you access methods to push and pop views
+ * on the navigation stack.
+ *
+ * @category Navigation
+ */
 export declare const useNavigation: () => {
     push: (node: import("react").ReactNode) => void;
     pop: () => void;

package/dist/api/hooks/use-navigation.js

@@ -6,6 +6,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.useNavigation = void 0;
 const react_1 = require("react");
 const navigation_context_1 = __importDefault(require("../context/navigation-context"));
+/**
+ * A React hook that lets you access methods to push and pop views
+ * on the navigation stack.
+ *
+ * @category Navigation
+ */
 const useNavigation = () => {
     const { push, pop } = (0, react_1.useContext)(navigation_context_1.default);
     return { push, pop };

package/dist/api/icon.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Image
+ */
 export declare enum Icon {
     AddPerson = "add-person",
     Airplane = "airplane",

package/dist/api/icon.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Icon = void 0;
+/**
+ * @category Image
+ */
 var Icon;
 (function (Icon) {
     Icon["AddPerson"] = "add-person";

package/dist/api/image.d.ts

@@ -1,14 +1,24 @@
 import { type ColorLike } from "./color";
 import type { Icon } from "./icon";
 import * as ui from "./proto/ui";
+/**
+ * Representation of an image, renderable everywhere Vicine expects them.
+ * @category Image
+ */
 export type Image = {
     source: Image.Source;
     fallback?: Image.Fallback | undefined | null;
     tintColor?: ColorLike | undefined | null;
     mask?: Image.Mask | undefined | null;
 };
+/**
+ * @category Image
+ */
 export type ImageLike = Image.ImageLike;
 export type SerializedImageLike = URL | Image.Asset | Icon | ui.Image | Image.ThemedImage;
+/**
+ * @category Image
+ */
 export declare namespace Image {
     type Asset = string;
     type ThemedSource = {
@@ -17,11 +27,11 @@ export declare namespace Image {
     };
     type Fallback = Source;
     type Source = URL | Asset | ThemedSource;
-    type ImageLike = URL | Image.Asset | Icon | Image | ThemedImage;
     type ThemedImage = {
         light: URL | Asset;
         dark: URL | Asset;
     };
+    type ImageLike = URL | Image.Asset | Icon | Image | Image.ThemedImage;
     enum Mask {
         Circle = "circle",
         RoundedRectangle = "roundedRectangle"

package/dist/api/image.js

@@ -36,6 +36,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.serializeProtoImage = exports.Image = void 0;
 const color_1 = require("./color");
 const ui = __importStar(require("./proto/ui"));
+/**
+ * @category Image
+ */
 var Image;
 (function (Image) {
     let Mask;

package/dist/api/index.d.ts

@@ -3,9 +3,9 @@ export * from "./components/index.js";
 export * from "./hooks/index.js";
 export * from "./context/index.js";
 export * from "./bus.js";
-export * from "./color.js";
+export { Color, ColorLike } from "./color.js";
 export * from "./keyboard.js";
-export * from "./image.js";
+export { ImageLike, Image } from "./image.js";
 export * from "./icon.js";
 export * from "./environment.js";
 export * from "./controls.js";

package/dist/api/index.js

@@ -14,14 +14,17 @@ 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 });
+exports.Image = exports.Color = void 0;
 __exportStar(require("./ai.js"), exports);
 __exportStar(require("./components/index.js"), exports);
 __exportStar(require("./hooks/index.js"), exports);
 __exportStar(require("./context/index.js"), exports);
 __exportStar(require("./bus.js"), exports);
-__exportStar(require("./color.js"), exports);
+var color_js_1 = require("./color.js");
+Object.defineProperty(exports, "Color", { enumerable: true, get: function () { return color_js_1.Color; } });
 __exportStar(require("./keyboard.js"), exports);
-__exportStar(require("./image.js"), exports);
+var image_js_1 = require("./image.js");
+Object.defineProperty(exports, "Image", { enumerable: true, get: function () { return image_js_1.Image; } });
 __exportStar(require("./icon.js"), exports);
 __exportStar(require("./environment.js"), exports);
 __exportStar(require("./controls.js"), exports);

package/dist/api/keyboard.d.ts

@@ -1,5 +1,14 @@
+/**
+ * @category Keyboard
+ */
 export type KeyEquivalent = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" | "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "." | "," | ";" | "=" | "+" | "-" | "[" | "]" | "{" | "}" | "«" | "»" | "(" | ")" | "/" | "\\" | "'" | "`" | "§" | "^" | "@" | "$" | "return" | "delete" | "deleteForward" | "tab" | "arrowUp" | "arrowDown" | "arrowLeft" | "arrowRight" | "pageUp" | "pageDown" | "home" | "end" | "space" | "escape" | "enter" | "backspace";
+/**
+ * @category Keyboard
+ */
 export type KeyModifier = "cmd" | "ctrl" | "opt" | "shift";
+/**
+ * @category Keyboard
+ */
 export declare namespace Keyboard {
     namespace Shortcut {
         type Common = "copy" | "copy-deeplink" | "copy-name" | "copy-path" | "save" | "duplicate" | "edit" | "move-down" | "move-up" | "new" | "open" | "open-with" | "pin" | "refresh" | "remove" | "remove-all";

package/dist/api/keyboard.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Keyboard = void 0;
+/**
+ * @category Keyboard
+ */
 var Keyboard;
 (function (Keyboard) {
     let Shortcut;

package/dist/api/local-storage.d.ts

@@ -1,13 +1,14 @@
+/**
+ * @category Local Storage
+ */
 export declare namespace LocalStorage {
     type Value = string | number | boolean;
     type Values = {
         [key: string]: Value;
     };
-}
-export declare class LocalStorage {
-    static getItem<T extends LocalStorage.Value>(key: string): Promise<T | undefined>;
-    static setItem(key: string, value: LocalStorage.Value): Promise<void>;
-    static removeItem(key: string): Promise<void>;
-    static allItems(): Promise<LocalStorage.Values>;
-    static clear(): Promise<void>;
+    function getItem<T extends LocalStorage.Value>(key: string): Promise<T | undefined>;
+    function setItem(key: string, value: LocalStorage.Value): Promise<void>;
+    function removeItem(key: string): Promise<void>;
+    function allItems(): Promise<LocalStorage.Values>;
+    function clear(): Promise<void>;
 }

package/dist/api/local-storage.js

@@ -2,28 +2,37 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LocalStorage = void 0;
 const bus_1 = require("./bus");
-class LocalStorage {
-    static async getItem(key) {
+// Implementation of Raycast's storage API: https://developers.raycast.com/api-reference/storage
+/**
+ * @category Local Storage
+ */
+var LocalStorage;
+(function (LocalStorage) {
+    async function getItem(key) {
         const res = await bus_1.bus.turboRequest("storage.get", { key });
         if (!res.ok || res.value.value === null) {
             return undefined;
         }
         return res.value.value;
     }
-    static async setItem(key, value) {
+    LocalStorage.getItem = getItem;
+    async function setItem(key, value) {
         await bus_1.bus.turboRequest("storage.set", { key, value });
     }
-    static async removeItem(key) {
+    LocalStorage.setItem = setItem;
+    async function removeItem(key) {
         await bus_1.bus.turboRequest("storage.remove", { key });
     }
-    static async allItems() {
+    LocalStorage.removeItem = removeItem;
+    async function allItems() {
         const res = await bus_1.bus.turboRequest("storage.list", {});
         if (!res.ok)
             return {};
         return res.value.values;
     }
-    static async clear() {
+    LocalStorage.allItems = allItems;
+    async function clear() {
         await bus_1.bus.turboRequest("storage.clear", {});
     }
-}
-exports.LocalStorage = LocalStorage;
+    LocalStorage.clear = clear;
+})(LocalStorage || (exports.LocalStorage = LocalStorage = {}));

package/dist/api/oauth.d.ts

@@ -21,6 +21,9 @@ declare enum OauthRedirectMethod {
      */
     AppURI = "appURI"
 }
+/**
+ * @category OAuth
+ */
 export declare namespace OAuth {
     namespace PKCEClient {
         /**
@@ -243,6 +246,9 @@ export declare namespace OAuth {
         scope?: string;
     }
 }
+/**
+ * @category OAuth
+ */
 export declare class PKCEClient {
     redirectMethod: OAuth.RedirectMethod;
     providerName: string;
@@ -298,15 +304,11 @@ export declare class PKCEClient {
      */
     removeTokens(): Promise<void>;
 }
-export type TokenSet = {
-    accessToken: string;
-    refreshToken?: string;
-    idToken?: string;
-    expiresIn?: number;
-    scope?: string;
-    updatedAt: Date;
-    isExpired: () => boolean;
-};
+/**
+ * Main OAuth object exporting all OAuth utilities
+ *
+ * @category OAuth
+ */
 export declare const OAuth: {
     PKCEClient: typeof PKCEClient;
     RedirectMethod: typeof OauthRedirectMethod;

package/dist/api/oauth.js

@@ -27,6 +27,9 @@ var OauthRedirectMethod;
      */
     OauthRedirectMethod["AppURI"] = "appURI";
 })(OauthRedirectMethod || (OauthRedirectMethod = {}));
+/**
+ * @category OAuth
+ */
 class PKCEClient {
     redirectMethod;
     providerName;
@@ -193,6 +196,22 @@ class PKCEClient {
     }
 }
 exports.PKCEClient = PKCEClient;
+/*
+export type TokenSet = {
+    accessToken: string;
+    refreshToken?: string;
+    idToken?: string;
+    expiresIn?: number;
+    scope?: string;
+    updatedAt: Date;
+    isExpired: () => boolean;
+};
+*/
+/**
+ * Main OAuth object exporting all OAuth utilities
+ *
+ * @category OAuth
+ */
 exports.OAuth = {
     PKCEClient,
     RedirectMethod: OauthRedirectMethod,

package/dist/api/preference.d.ts

@@ -1,5 +1,13 @@
 export declare const getPreferenceValues: <T = {
     [preferenceName: string]: any;
 }>() => T;
+/**
+ * TODO: implement
+ * @ignore
+ */
 export declare const openExtensionPreferences: () => Promise<void>;
+/**
+ * TODO: implement
+ * @ignore
+ */
 export declare const openCommandPreferences: () => Promise<void>;

package/dist/api/preference.js

@@ -7,10 +7,18 @@ const getPreferenceValues = () => {
     return preferenceValues;
 };
 exports.getPreferenceValues = getPreferenceValues;
+/**
+ * TODO: implement
+ * @ignore
+ */
 const openExtensionPreferences = async () => {
     console.error("openExtensionPreferences is not implemented");
 };
 exports.openExtensionPreferences = openExtensionPreferences;
+/**
+ * TODO: implement
+ * @ignore
+ */
 const openCommandPreferences = async () => {
     console.error("openCommandPreferences is not implemented");
 };

package/dist/api/toast.d.ts

@@ -16,6 +16,8 @@ import { Keyboard } from "./keyboard";
  *   toast.title = "Uploaded image";
  * };
  * ```
+ *
+ * @category Toast
  */
 export declare class Toast {
     private options;
@@ -65,6 +67,9 @@ export declare class Toast {
      */
     hide(): Promise<void>;
 }
+/**
+ * @category Toast
+ */
 export declare namespace Toast {
     /**
      * The options to create a {@link Toast}.
@@ -156,4 +161,7 @@ export declare interface ToastOptions extends Toast.Options {
  * @deprecated Use {@link Toast.Style} instead
  */
 export declare const ToastStyle: typeof Toast.Style;
+/**
+ * @category Toast
+ */
 export declare const showToast: (init: Toast.Style | Toast.Options, title?: string, message?: string) => Promise<Toast>;

package/dist/api/toast.js

@@ -54,6 +54,8 @@ const ui = __importStar(require("./proto/ui"));
  *   toast.title = "Uploaded image";
  * };
  * ```
+ *
+ * @category Toast
  */
 class Toast {
     options;
@@ -184,6 +186,9 @@ class Toast {
     }
 }
 exports.Toast = Toast;
+/**
+ * @category Toast
+ */
 (function (Toast) {
     /**
      * Defines the visual style of the Toast.
@@ -200,6 +205,9 @@ exports.Toast = Toast;
         Style["Animated"] = "animated";
     })(Style = Toast.Style || (Toast.Style = {}));
 })(Toast || (exports.Toast = Toast = {}));
+/**
+ * @category Toast
+ */
 const showToast = async (init, title = "", message) => {
     const toast = typeof init === "string"
         ? new Toast({ style: init, message, title })

package/dist/api/utils.d.ts

@@ -1,11 +1,16 @@
-import { PathLike } from "fs";
-import { Application } from "./proto/application";
+import type { PathLike } from "node:fs";
+import type { Application } from "./proto/application";
+/**
+  @ignore - we should probably move this to raycast compat, I don't think we want that.
+ */
 export declare const trash: (path: PathLike | PathLike[]) => Promise<void>;
 /**
  * Additional options that can be passed in order to tweak the behavior of the terminal window.
  * Note that most options are best-effort, which means that they may or may not work depending on
  * the default terminal emulator that is available.
  * On Linux, Vicinae honors the xdg-terminal-exec specification: https://gitlab.freedesktop.org/terminal-wg/specifications/-/merge_requests/3/diffs
+ *
+ * @category System
  */
 export type RunInTerminalOptions = {
     /**
@@ -42,11 +47,28 @@ export type RunInTerminalOptions = {
  * // or, inside a shell:
  * await runInTerminal(['/bin/bash', 'echo "dis is my home: $HOME"'], { hold: true });
  * ```
+ *
+ * @category System
  */
 export declare const runInTerminal: (args: string[], options?: RunInTerminalOptions) => Promise<void>;
+/**
+ * @category System
+ */
 export declare const open: (target: string, app?: Application | string) => Promise<void>;
+/**
+ * @category System
+ */
 export declare const getFrontmostApplication: () => Promise<Application>;
+/**
+ * @category System
+ */
 export declare const getApplications: (target?: string) => Promise<Application[]>;
+/**
+ * @category System
+ */
 export declare const getDefaultApplication: (path: string) => Promise<Application>;
+/**
+ * @category System
+ */
 export declare const showInFileBrowser: (path: PathLike) => Promise<void>;
 export { Application } from "./proto/application";

package/dist/api/utils.js

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Application = exports.showInFileBrowser = exports.getDefaultApplication = exports.getApplications = exports.getFrontmostApplication = exports.open = exports.runInTerminal = exports.trash = void 0;
-const promises_1 = require("fs/promises");
+const promises_1 = require("node:fs/promises");
 const bus_1 = require("./bus");
 const window_management_1 = require("./window-management");
-// Linux systems usually do not have a trash, but maybe we should support one...
+/**
+  @ignore - we should probably move this to raycast compat, I don't think we want that.
+ */
 const trash = async (path) => {
     const targets = Array.isArray(path) ? path : [path];
     const promises = targets.map((p) => (0, promises_1.rm)(p, { recursive: true }));
@@ -23,6 +25,8 @@ exports.trash = trash;
  * // or, inside a shell:
  * await runInTerminal(['/bin/bash', 'echo "dis is my home: $HOME"'], { hold: true });
  * ```
+ *
+ * @category System
  */
 const runInTerminal = async (args, options = {}) => {
     const { hold = false, appId, title } = options;
@@ -34,6 +38,9 @@ const runInTerminal = async (args, options = {}) => {
     });
 };
 exports.runInTerminal = runInTerminal;
+/**
+ * @category System
+ */
 const open = async (target, app) => {
     let appId;
     if (app) {
@@ -50,6 +57,9 @@ const open = async (target, app) => {
     });
 };
 exports.open = open;
+/**
+ * @category System
+ */
 const getFrontmostApplication = async () => {
     const { application } = await window_management_1.WindowManagement.getActiveWindow();
     if (!application) {
@@ -58,11 +68,17 @@ const getFrontmostApplication = async () => {
     return application;
 };
 exports.getFrontmostApplication = getFrontmostApplication;
+/**
+ * @category System
+ */
 const getApplications = async (target) => {
     const res = await bus_1.bus.turboRequest("app.list", { target });
     return res.unwrap().apps;
 };
 exports.getApplications = getApplications;
+/**
+ * @category System
+ */
 const getDefaultApplication = async (path) => {
     const res = await bus_1.bus.turboRequest("app.getDefault", { target: path });
     const app = res.unwrap().app;
@@ -71,6 +87,9 @@ const getDefaultApplication = async (path) => {
     return app;
 };
 exports.getDefaultApplication = getDefaultApplication;
+/**
+ * @category System
+ */
 const showInFileBrowser = async (path) => {
     const fileBrowser = await (0, exports.getDefaultApplication)("inode/directory"); // FIXME: we may want something more robust
     await (0, exports.open)(path.toString(), fileBrowser);

package/dist/api/window-management.d.ts

@@ -13,7 +13,7 @@ import * as wm from "./proto/wm";
  *
  * const windows = await WindowManagement.getWindows();
  * ```
- *
+ * @category Window Management
  * @public
  */
 export declare namespace WindowManagement {

package/dist/api/window-management.js

@@ -35,7 +35,7 @@ const transformWindow = (proto) => {
  *
  * const windows = await WindowManagement.getWindows();
  * ```
- *
+ * @category Window Management
  * @public
  */
 var WindowManagement;

package/package.json

@@ -1,14 +1,13 @@
 {
 	"name": "@vicinae/api",
-	"version": "0.16.4",
+	"version": "0.16.6",
 	"description": "TypeScript SDK to build Vicinae extensions",
 	"scripts": {
 		"test": "echo \"Error: no test specified\" && exit 1",
 		"build": "tsc --outDir dist",
 		"protogen": "mkdir -p ./src/api/proto && protoc --plugin=./node_modules/.bin/protoc-gen-ts_proto -I../../proto ../../proto/*.proto --ts_proto_out ./src/api/proto",
 		"pack": "npm run build && npm pack",
-		"docgen-html": "typedoc src/api/index.ts",
-		"docgen-md": "typedoc src/api/index.ts --disableSources --readme none --plugin typedoc-plugin-markdown --out ./docs",
+		"docgen": "typedoc",
 		"format": "biome format --write"
 	},
 	"bin": {
@@ -58,6 +57,7 @@
 		"ts-node": "^10",
 		"ts-proto": "^2.7.5",
 		"typedoc": "^0.28.13",
+		"typedoc-github-theme": "^0.3.1",
 		"typedoc-plugin-markdown": "^4.8.1",
 		"typescript": "^5"
 	},

package/types/jsx.d.ts

@@ -107,7 +107,7 @@ declare module "react" {
 			};
 			"metadata-label": {
 				title: string;
-				text: string;
+				text: string | { color?: SerializedColorLike; value: string };
 				icon?: SerializedImageLike;
 			};
 			"metadata-separator": {};

package/dist/api/hooks/use-applications.d.ts

@@ -1,2 +0,0 @@
-import { Application } from "../utils";
-export declare const useApplications: () => [Application[], boolean, Error | null];

package/dist/api/hooks/use-applications.js

@@ -1,19 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.useApplications = void 0;
-const react_1 = require("react");
-const utils_1 = require("../utils");
-const useApplications = () => {
-    const [isLoading, setIsLoading] = (0, react_1.useState)(true);
-    const [error, setError] = (0, react_1.useState)(null);
-    const [apps, setApps] = (0, react_1.useState)([]);
-    (0, react_1.useEffect)(() => {
-        setIsLoading(true);
-        (0, utils_1.getApplications)()
-            .then(setApps)
-            .catch(setError)
-            .finally(() => setIsLoading(false));
-    }, []);
-    return [apps, isLoading, error];
-};
-exports.useApplications = useApplications;