@lapis-notes/api 0.1.0

package/dist/app-url.js

@@ -0,0 +1,269 @@
+import { TFile } from "./storage/fs";
+import { NativeDesktopVaultAdapter, resolveNativeDesktopVaultPathToRelative, } from "./storage/desktop-native";
+import { getAdapterVaultId } from "./storage/vault-state";
+const SUPPORTED_APP_URL_SCHEMES = new Set([
+    "lapis",
+    "lapis-notes",
+    "web+lapis",
+    "obsidian",
+]);
+function looseDecode(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+function decodePathname(pathname) {
+    return pathname
+        .split("/")
+        .map((segment) => looseDecode(segment))
+        .join("/");
+}
+function normalizeScheme(protocol) {
+    return protocol.replace(/:$/u, "").toLowerCase();
+}
+function normalizeParamValue(value) {
+    if (value == null) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+function createParams(url) {
+    const params = {};
+    for (const [key, value] of url.searchParams.entries()) {
+        params[key] = value;
+    }
+    return params;
+}
+function stripFileSubpath(path) {
+    return path.split(/[|#]/u, 1)[0] ?? path;
+}
+function normalizeVaultFilePath(path) {
+    return stripFileSubpath(path).replace(/^\/+/u, "").replace(/\/+$/u, "");
+}
+function encodeAppUrlParam(value) {
+    return encodeURIComponent(value).replace(/%2F/giu, "%2F");
+}
+function createUrl(rawUrl) {
+    try {
+        return new URL(rawUrl);
+    }
+    catch {
+        return new URL(rawUrl.replace(/ /gu, "%20"));
+    }
+}
+function currentVaultAliases(app) {
+    const adapter = app.vault.adapter;
+    const values = [
+        app.vault.getName(),
+        app.session?.profile?.id,
+        app.session?.profile?.name,
+        app.session ? getAdapterVaultId(app.session.vaultAdapter) : undefined,
+        adapter.getVaultId?.(),
+        app.appDatabase.vaultId,
+    ];
+    return new Set(values.filter((value) => Boolean(value)));
+}
+function matchesCurrentVault(app, vault) {
+    if (!vault) {
+        return true;
+    }
+    return currentVaultAliases(app).has(vault);
+}
+function resolveFile(app, rawFile) {
+    const filePath = normalizeVaultFilePath(rawFile);
+    if (!filePath) {
+        return null;
+    }
+    const candidates = [filePath, `${filePath}.md`, `${filePath}.markdown`];
+    for (const candidate of candidates) {
+        const file = app.vault.getFileByPath(candidate);
+        if (file instanceof TFile) {
+            return file;
+        }
+    }
+    if (!filePath.includes("/")) {
+        return (app.vault
+            .getAllLoadedFiles()
+            .filter((file) => file instanceof TFile)
+            .find((file) => file.baseName === filePath ||
+            file.basename === filePath ||
+            file.path === filePath) ?? null);
+    }
+    return null;
+}
+function paneTypeFromParams(params) {
+    const paneType = params["paneType"];
+    if (paneType === "tab" || paneType === "split" || paneType === "window") {
+        return paneType;
+    }
+    return undefined;
+}
+export function createLapisOpenUrl(options) {
+    const params = new URLSearchParams();
+    params.set("vault", options.vault);
+    if (options.path) {
+        params.set("path", options.path);
+    }
+    else if (options.file) {
+        params.set("file", options.file);
+    }
+    if (options.paneType) {
+        params.set("paneType", options.paneType);
+    }
+    return `lapis://open?${params.toString()}`;
+}
+export function createLapisFileUrl(vault, file) {
+    return `lapis://open?vault=${encodeAppUrlParam(vault)}&file=${encodeAppUrlParam(file)}`;
+}
+/**
+ * Parses `lapis://` app URLs and dispatches registered protocol handlers.
+ *
+ * @public
+ */
+export class AppUrlService {
+    app;
+    #handlers = new Map();
+    constructor(app) {
+        this.app = app;
+    }
+    /**
+     * Register a handler for a custom app URL action.
+     *
+     * @param action - Action name to match after the app URL scheme.
+     * @param handler - Callback invoked when a matching URL is dispatched.
+     * @returns A cleanup function that unregisters the handler.
+     * @public
+     */
+    registerProtocolHandler(action, handler) {
+        const normalizedAction = action.trim();
+        if (!normalizedAction) {
+            throw new Error("Protocol handler action is required");
+        }
+        const handlers = this.#handlers.get(normalizedAction) ?? new Set();
+        handlers.add(handler);
+        this.#handlers.set(normalizedAction, handlers);
+        return () => {
+            handlers.delete(handler);
+            if (!handlers.size) {
+                this.#handlers.delete(normalizedAction);
+            }
+        };
+    }
+    /**
+     * Parse an app URL into its normalized action and parameter map.
+     *
+     * @param rawUrl - Raw `lapis://`, `lapis-notes://`, or compatible app URL.
+     * @returns The normalized URL request.
+     * @public
+     */
+    parse(rawUrl) {
+        const url = createUrl(rawUrl);
+        const scheme = normalizeScheme(url.protocol);
+        if (!SUPPORTED_APP_URL_SCHEMES.has(scheme)) {
+            throw new Error(`Unsupported app URL scheme: ${scheme}`);
+        }
+        const params = createParams(url);
+        const hostAction = looseDecode(url.hostname);
+        if (!hostAction && url.pathname) {
+            return {
+                scheme,
+                action: "open",
+                params: {
+                    ...params,
+                    action: "open",
+                    path: decodePathname(url.pathname),
+                },
+            };
+        }
+        if (hostAction === "vault") {
+            const segments = url.pathname
+                .split("/")
+                .filter(Boolean)
+                .map((segment) => looseDecode(segment));
+            const [vault, ...fileParts] = segments;
+            return {
+                scheme,
+                action: "open",
+                params: {
+                    ...params,
+                    action: "open",
+                    ...(vault ? { vault } : {}),
+                    ...(fileParts.length ? { file: fileParts.join("/") } : {}),
+                },
+            };
+        }
+        const action = hostAction || "open";
+        return {
+            scheme,
+            action,
+            params: {
+                ...params,
+                action,
+            },
+        };
+    }
+    /**
+     * Dispatch an app URL through the built-in open handler or a registered
+     * custom action.
+     *
+     * @param rawUrl - Raw app URL to parse and execute.
+     * @returns `true` when the URL was handled successfully.
+     * @public
+     */
+    async dispatch(rawUrl) {
+        const request = this.parse(rawUrl);
+        if (request.action === "open") {
+            return this.open(request.params);
+        }
+        const handlers = this.#handlers.get(request.action);
+        if (!handlers?.size) {
+            return false;
+        }
+        await Promise.all([...handlers].map((handler) => handler(request.params)));
+        return true;
+    }
+    async open(params) {
+        const vault = normalizeParamValue(params["vault"]);
+        if (!matchesCurrentVault(this.app, vault)) {
+            return false;
+        }
+        let targetFile = normalizeParamValue(params["file"]);
+        const absolutePath = normalizeParamValue(params["path"]);
+        if (absolutePath) {
+            const adapter = this.app.vault.adapter;
+            if (!(adapter instanceof NativeDesktopVaultAdapter)) {
+                return false;
+            }
+            targetFile =
+                (await resolveNativeDesktopVaultPathToRelative(adapter.rootPath, absolutePath)) ?? undefined;
+            if (!targetFile) {
+                return false;
+            }
+        }
+        if (!targetFile) {
+            return true;
+        }
+        const file = resolveFile(this.app, targetFile);
+        if (!file) {
+            return false;
+        }
+        const paneType = paneTypeFromParams(params);
+        if (!paneType) {
+            await this.app.openFile(file);
+            return true;
+        }
+        try {
+            const leaf = this.app.workspace.getLeaf(paneType);
+            this.app.workspace.activeLeaf = leaf;
+            await leaf.openFile(file);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/dist/application-compatibility.d.ts

@@ -0,0 +1,31 @@
+import type { App } from "./context.svelte";
+declare global {
+    /**
+     * Legacy application alias retained for Obsidian-compatible plugins.
+     *
+     * First-party code should receive an {@link App} explicitly or resolve it
+     * from Svelte context instead of depending on this process-wide value.
+     *
+     * @public
+     */
+    var app: App;
+}
+/** Return the current legacy application alias, when one is installed. */
+export declare function getApplicationCompatibility(): App | undefined;
+/**
+ * Resolve an application supplied by its owner, falling back to the legacy
+ * global alias only for compatibility.
+ *
+ * @public
+ */
+export declare function resolveApplication(application?: App): App;
+/**
+ * Install a managed lease for the legacy `globalThis.app` alias.
+ *
+ * The newest live lease is exposed. Disposing leases out of order is safe,
+ * and disposing the final lease restores the value that existed before the
+ * first lease was installed.
+ *
+ * @public
+ */
+export declare function installApplicationCompatibility(application: App): () => void;

package/dist/application-compatibility.js

@@ -0,0 +1,64 @@
+const leases = [];
+let previousApplication;
+let hadPreviousApplication = false;
+/** Return the current legacy application alias, when one is installed. */
+export function getApplicationCompatibility() {
+    return globalThis.app;
+}
+/**
+ * Resolve an application supplied by its owner, falling back to the legacy
+ * global alias only for compatibility.
+ *
+ * @public
+ */
+export function resolveApplication(application) {
+    const resolved = application ?? getApplicationCompatibility();
+    if (!resolved) {
+        throw new Error("No Lapis application is available. Pass an App explicitly, call provideApplicationState() in a component owner, or install the legacy compatibility alias.");
+    }
+    return resolved;
+}
+/**
+ * Install a managed lease for the legacy `globalThis.app` alias.
+ *
+ * The newest live lease is exposed. Disposing leases out of order is safe,
+ * and disposing the final lease restores the value that existed before the
+ * first lease was installed.
+ *
+ * @public
+ */
+export function installApplicationCompatibility(application) {
+    if (leases.length === 0) {
+        hadPreviousApplication = Object.prototype.hasOwnProperty.call(globalThis, "app");
+        previousApplication = getApplicationCompatibility();
+    }
+    const lease = { application, token: Symbol("application-compatibility") };
+    leases.push(lease);
+    globalThis.app = application;
+    let disposed = false;
+    return () => {
+        if (disposed)
+            return;
+        disposed = true;
+        const index = leases.findIndex((candidate) => candidate.token === lease.token);
+        if (index === -1)
+            return;
+        const wasActive = index === leases.length - 1;
+        leases.splice(index, 1);
+        if (!wasActive)
+            return;
+        const next = leases.at(-1);
+        if (next) {
+            globalThis.app = next.application;
+            return;
+        }
+        if (hadPreviousApplication) {
+            globalThis.app = previousApplication;
+        }
+        else {
+            delete globalThis.app;
+        }
+        previousApplication = undefined;
+        hadPreviousApplication = false;
+    };
+}

package/dist/application-state.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { App } from "./context.svelte";
+/**
+ * Provide an application to the current Svelte component subtree.
+ *
+ * @public
+ */
+export declare function provideApplicationState(application: App): App;
+/**
+ * Resolve the owning application in explicit, component-context, then legacy
+ * compatibility order.
+ *
+ * @public
+ */
+export declare function useApplicationState(application?: App): App;

package/dist/application-state.svelte.js

@@ -0,0 +1,30 @@
+import { getContext, setContext } from "svelte";
+import { resolveApplication } from "./application-compatibility";
+const APPLICATION_STATE = Symbol("lapis-application-state");
+/**
+ * Provide an application to the current Svelte component subtree.
+ *
+ * @public
+ */
+export function provideApplicationState(application) {
+    return setContext(APPLICATION_STATE, application);
+}
+/**
+ * Resolve the owning application in explicit, component-context, then legacy
+ * compatibility order.
+ *
+ * @public
+ */
+export function useApplicationState(application) {
+    if (application)
+        return application;
+    let contextualApplication;
+    try {
+        contextualApplication = getContext(APPLICATION_STATE);
+    }
+    catch {
+        // getContext is only valid during component initialization. Plain classes
+        // continue through the deliberately narrow compatibility fallback.
+    }
+    return resolveApplication(contextualApplication);
+}