@lapis-notes/api 0.1.0

package/dist/notifications.d.ts

@@ -0,0 +1,209 @@
+import { EventDispatcher } from "./events";
+import type { AppDatabaseNotificationRecord, AppDatabaseNotificationSeverity } from "./storage/app-database";
+export type NotificationSeverity = AppDatabaseNotificationSeverity;
+export type NotificationLocation = "status" | "notification" | "silent";
+export type NotificationProgressStatus = "running" | "cancelling" | "completed" | "failed" | "cancelled";
+/**
+ * Options for creating a one-shot notification record.
+ *
+ * @public
+ */
+export interface NotifyOptions {
+    id?: string;
+    title?: string;
+    message: string;
+    severity?: NotificationSeverity;
+    source?: string;
+    persist?: boolean;
+}
+/**
+ * Options for creating a long-running progress item.
+ *
+ * @public
+ */
+export interface NotificationProgressOptions {
+    id?: string;
+    title: string;
+    message?: string;
+    source?: string;
+    location?: NotificationLocation;
+    cancellable?: boolean;
+    persistOnComplete?: boolean;
+    persistOnError?: boolean;
+}
+/**
+ * Incremental progress update payload passed to a running progress handle.
+ *
+ * @public
+ */
+export interface NotificationProgressReport {
+    message?: string;
+    current?: number;
+    total?: number;
+    increment?: number;
+    indeterminate?: boolean;
+}
+/**
+ * Serializable view of the current progress state.
+ *
+ * @public
+ */
+export interface NotificationProgressSnapshot {
+    id: string;
+    title: string;
+    message?: string;
+    source?: string;
+    location: NotificationLocation;
+    status: NotificationProgressStatus;
+    cancellable: boolean;
+    cancelRequested: boolean;
+    current?: number;
+    total?: number;
+    percent?: number;
+    indeterminate: boolean;
+    startedAt: number;
+    updatedAt: number;
+    error?: string;
+}
+/**
+ * Cancellation token exposed to long-running tasks started through the
+ * notification progress API.
+ *
+ * @public
+ */
+export interface NotificationProgressToken {
+    readonly signal: AbortSignal;
+    readonly isCancellationRequested: boolean;
+    throwIfCancellationRequested(): void;
+}
+type NotificationEvents = {
+    changed: [];
+    notify: [record: AppDatabaseNotificationRecord];
+};
+/**
+ * Mutable handle returned for a running progress item.
+ *
+ * @public
+ */
+export declare class NotificationProgressHandle implements NotificationProgressToken {
+    private readonly manager;
+    readonly id: string;
+    readonly signal: AbortSignal;
+    private controller;
+    private snapshot;
+    private completed;
+    constructor(manager: NotificationManager, options: NotificationProgressOptions);
+    get isCancellationRequested(): boolean;
+    get currentSnapshot(): NotificationProgressSnapshot;
+    /**
+     * Update the current progress state.
+     *
+     * @param report - Partial progress information to merge into the live state.
+     * @public
+     */
+    report(report: NotificationProgressReport): void;
+    /**
+     * Alias for {@link report}.
+     *
+     * @param report - Partial progress information to merge into the live state.
+     * @public
+     */
+    update(report: NotificationProgressReport): void;
+    /**
+     * Request cancellation for the running progress item.
+     *
+     * @public
+     */
+    cancel(): void;
+    /**
+     * Mark the progress item as completed.
+     *
+     * @param message - Optional terminal message shown to the user.
+     * @public
+     */
+    complete(message?: string): void;
+    /**
+     * Mark the progress item as failed.
+     *
+     * @param error - Failure value to surface in the final progress state.
+     * @public
+     */
+    fail(error: unknown): void;
+    /**
+     * Mark the progress item as cancelled.
+     *
+     * @param message - Optional terminal message shown after cancellation.
+     * @public
+     */
+    cancelled(message?: string): void;
+    /**
+     * Throw an abort error when cancellation has been requested.
+     *
+     * @public
+     */
+    throwIfCancellationRequested(): void;
+    private finish;
+}
+/**
+ * Records user-visible notifications and tracks live progress handles.
+ *
+ * @public
+ */
+export declare class NotificationManager extends EventDispatcher<NotificationEvents> {
+    private readonly database;
+    records: AppDatabaseNotificationRecord[];
+    activeProgress: NotificationProgressSnapshot[];
+    private progressHandles;
+    constructor(database: {
+        listNotifications(): Promise<AppDatabaseNotificationRecord[]>;
+        upsertNotification(record: AppDatabaseNotificationRecord): Promise<void>;
+        markNotificationRead(id: string): Promise<void>;
+        clearNotification(id: string): Promise<void>;
+        clearAllNotifications(): Promise<void>;
+    });
+    /**
+     * Load persisted notification history for the current vault.
+     *
+     * @public
+     */
+    loadPersisted(): Promise<void>;
+    /**
+     * Return the current persisted notification history.
+     *
+     * @public
+     */
+    list(): AppDatabaseNotificationRecord[];
+    /**
+     * Record a notification and optionally persist it to history.
+     *
+     * @param options - Notification payload or a shorthand message string.
+     * @returns The recorded notification snapshot.
+     * @public
+     */
+    notify(options: NotifyOptions | string): AppDatabaseNotificationRecord;
+    /**
+     * Create a mutable progress handle for a long-running task.
+     *
+     * @param options - Progress metadata shown to the user.
+     * @returns The new progress handle.
+     * @public
+     */
+    createProgress(options: NotificationProgressOptions): NotificationProgressHandle;
+    /**
+     * Run a task with a managed progress handle.
+     *
+     * @param options - Progress metadata shown to the user.
+     * @param task - Task that receives the progress handle and cancellation
+     *   token.
+     * @returns The task result.
+     * @public
+     */
+    withProgress<T>(options: NotificationProgressOptions, task: (progress: NotificationProgressHandle, token: NotificationProgressToken) => Promise<T> | T): Promise<T>;
+    cancel(id: string): void;
+    markRead(id: string): Promise<void>;
+    clear(id: string): Promise<void>;
+    clearAll(): Promise<void>;
+    updateProgress(snapshot: NotificationProgressSnapshot): void;
+    finishProgress(snapshot: NotificationProgressSnapshot): void;
+}
+export {};

package/dist/notifications.js

@@ -0,0 +1,338 @@
+import { EventDispatcher } from "./events";
+function createNotificationId(prefix = "notification") {
+    if (typeof crypto !== "undefined" && "randomUUID" in crypto) {
+        return `${prefix}-${crypto.randomUUID()}`;
+    }
+    return `${prefix}-${Date.now().toString(36)}-${Math.random()
+        .toString(36)
+        .slice(2)}`;
+}
+function cloneRecord(record) {
+    return { ...record };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+class CancellationError extends Error {
+    constructor() {
+        super("Operation cancelled");
+        this.name = "AbortError";
+    }
+}
+/**
+ * Mutable handle returned for a running progress item.
+ *
+ * @public
+ */
+export class NotificationProgressHandle {
+    manager;
+    id;
+    signal;
+    controller;
+    snapshot;
+    completed = false;
+    constructor(manager, options) {
+        this.manager = manager;
+        this.id = options.id ?? createNotificationId("progress");
+        this.controller = new AbortController();
+        this.signal = this.controller.signal;
+        const now = Date.now();
+        this.snapshot = {
+            id: this.id,
+            title: options.title,
+            message: options.message,
+            source: options.source,
+            location: options.location ?? "status",
+            status: "running",
+            cancellable: options.cancellable === true,
+            cancelRequested: false,
+            indeterminate: true,
+            startedAt: now,
+            updatedAt: now,
+        };
+    }
+    get isCancellationRequested() {
+        return this.signal.aborted;
+    }
+    get currentSnapshot() {
+        return { ...this.snapshot };
+    }
+    /**
+     * Update the current progress state.
+     *
+     * @param report - Partial progress information to merge into the live state.
+     * @public
+     */
+    report(report) {
+        if (this.completed) {
+            return;
+        }
+        const next = {
+            ...this.snapshot,
+            updatedAt: Date.now(),
+        };
+        if (report.message !== undefined) {
+            next.message = report.message;
+        }
+        if (typeof report.increment === "number") {
+            const previous = next.percent ?? 0;
+            next.percent = Math.max(0, Math.min(100, previous + report.increment));
+            next.current = next.percent;
+            next.total = 100;
+            next.indeterminate = false;
+        }
+        if (typeof report.current === "number" ||
+            typeof report.total === "number") {
+            next.current = report.current ?? next.current;
+            next.total = report.total ?? next.total;
+            if (typeof next.current === "number" && typeof next.total === "number") {
+                next.percent =
+                    next.total > 0
+                        ? Math.max(0, Math.min(100, (next.current / next.total) * 100))
+                        : 0;
+            }
+            next.indeterminate = false;
+        }
+        if (report.indeterminate === true) {
+            delete next.current;
+            delete next.total;
+            delete next.percent;
+            next.indeterminate = true;
+        }
+        this.snapshot = next;
+        this.manager.updateProgress(this.snapshot);
+    }
+    /**
+     * Alias for {@link report}.
+     *
+     * @param report - Partial progress information to merge into the live state.
+     * @public
+     */
+    update(report) {
+        this.report(report);
+    }
+    /**
+     * Request cancellation for the running progress item.
+     *
+     * @public
+     */
+    cancel() {
+        if (this.completed || !this.snapshot.cancellable) {
+            return;
+        }
+        this.snapshot = {
+            ...this.snapshot,
+            status: "cancelling",
+            cancelRequested: true,
+            updatedAt: Date.now(),
+        };
+        this.controller.abort();
+        this.manager.updateProgress(this.snapshot);
+    }
+    /**
+     * Mark the progress item as completed.
+     *
+     * @param message - Optional terminal message shown to the user.
+     * @public
+     */
+    complete(message) {
+        this.finish("completed", message);
+    }
+    /**
+     * Mark the progress item as failed.
+     *
+     * @param error - Failure value to surface in the final progress state.
+     * @public
+     */
+    fail(error) {
+        this.finish("failed", errorMessage(error), errorMessage(error));
+    }
+    /**
+     * Mark the progress item as cancelled.
+     *
+     * @param message - Optional terminal message shown after cancellation.
+     * @public
+     */
+    cancelled(message = "Cancelled") {
+        this.finish("cancelled", message);
+    }
+    /**
+     * Throw an abort error when cancellation has been requested.
+     *
+     * @public
+     */
+    throwIfCancellationRequested() {
+        if (this.signal.aborted) {
+            throw new CancellationError();
+        }
+    }
+    finish(status, message, error) {
+        if (this.completed) {
+            return;
+        }
+        this.completed = true;
+        this.snapshot = {
+            ...this.snapshot,
+            status,
+            message: message ?? this.snapshot.message,
+            error,
+            updatedAt: Date.now(),
+        };
+        this.manager.finishProgress(this.snapshot);
+    }
+}
+/**
+ * Records user-visible notifications and tracks live progress handles.
+ *
+ * @public
+ */
+export class NotificationManager extends EventDispatcher {
+    database;
+    records = [];
+    activeProgress = [];
+    progressHandles = new Map();
+    constructor(database) {
+        super();
+        this.database = database;
+    }
+    /**
+     * Load persisted notification history for the current vault.
+     *
+     * @public
+     */
+    async loadPersisted() {
+        this.records = await this.database.listNotifications();
+        this.trigger("changed");
+    }
+    /**
+     * Return the current persisted notification history.
+     *
+     * @public
+     */
+    list() {
+        return this.records.map(cloneRecord);
+    }
+    /**
+     * Record a notification and optionally persist it to history.
+     *
+     * @param options - Notification payload or a shorthand message string.
+     * @returns The recorded notification snapshot.
+     * @public
+     */
+    notify(options) {
+        const normalized = typeof options === "string" ? { message: options } : options;
+        const now = Date.now();
+        const record = {
+            id: normalized.id ?? createNotificationId(),
+            title: normalized.title,
+            message: normalized.message,
+            severity: normalized.severity ?? "info",
+            source: normalized.source,
+            createdAt: now,
+            updatedAt: now,
+            read: false,
+            cleared: false,
+        };
+        if (normalized.persist) {
+            this.records = [
+                record,
+                ...this.records.filter((it) => it.id !== record.id),
+            ];
+            void this.database.upsertNotification(record).catch((error) => {
+                console.warn("Failed to persist notification", error);
+            });
+            this.trigger("changed");
+        }
+        this.trigger("notify", cloneRecord(record));
+        return cloneRecord(record);
+    }
+    /**
+     * Create a mutable progress handle for a long-running task.
+     *
+     * @param options - Progress metadata shown to the user.
+     * @returns The new progress handle.
+     * @public
+     */
+    createProgress(options) {
+        const handle = new NotificationProgressHandle(this, options);
+        this.progressHandles.set(handle.id, handle);
+        this.updateProgress(handle.currentSnapshot);
+        return handle;
+    }
+    /**
+     * Run a task with a managed progress handle.
+     *
+     * @param options - Progress metadata shown to the user.
+     * @param task - Task that receives the progress handle and cancellation
+     *   token.
+     * @returns The task result.
+     * @public
+     */
+    async withProgress(options, task) {
+        const progress = this.createProgress(options);
+        try {
+            const result = await task(progress, progress);
+            progress.complete();
+            if (options.persistOnComplete) {
+                this.notify({
+                    title: options.title,
+                    message: progress.currentSnapshot.message ?? "Completed",
+                    severity: "info",
+                    source: options.source,
+                    persist: true,
+                });
+            }
+            return result;
+        }
+        catch (error) {
+            if (progress.signal.aborted) {
+                progress.cancelled();
+            }
+            else {
+                progress.fail(error);
+                if (options.persistOnError !== false) {
+                    this.notify({
+                        title: options.title,
+                        message: errorMessage(error),
+                        severity: "error",
+                        source: options.source,
+                        persist: true,
+                    });
+                }
+            }
+            throw error;
+        }
+    }
+    cancel(id) {
+        this.progressHandles.get(id)?.cancel();
+    }
+    async markRead(id) {
+        this.records = this.records.map((record) => record.id === id
+            ? { ...record, read: true, updatedAt: Date.now() }
+            : record);
+        this.trigger("changed");
+        await this.database.markNotificationRead(id);
+    }
+    async clear(id) {
+        this.records = this.records.filter((record) => record.id !== id);
+        this.trigger("changed");
+        await this.database.clearNotification(id);
+    }
+    async clearAll() {
+        this.records = [];
+        this.trigger("changed");
+        await this.database.clearAllNotifications();
+    }
+    updateProgress(snapshot) {
+        this.activeProgress = [
+            snapshot,
+            ...this.activeProgress.filter((entry) => entry.id !== snapshot.id),
+        ];
+        this.trigger("changed");
+    }
+    finishProgress(snapshot) {
+        this.progressHandles.delete(snapshot.id);
+        this.activeProgress = this.activeProgress.filter((entry) => entry.id !== snapshot.id);
+        this.trigger("changed");
+    }
+}

package/dist/open-file.d.ts

@@ -0,0 +1,23 @@
+import type { TFile } from "./storage";
+import type { View, ViewState } from "./view.svelte";
+import { type OpenViewState, type WorkspaceLeaf } from "./workspace.svelte";
+type LeafLike = {
+    view: unknown;
+};
+type OpenFileWorkspaceLike<Leaf extends LeafLike> = {
+    getFocusedCommandHostId(): string;
+    getCommandHostIdForLeaf(target: Leaf | null): string;
+    iterateAllLeaves<T>(callback: (leaf: Leaf) => T): T | void;
+};
+export declare function leafFilePath(leaf: LeafLike | null | undefined): string | null;
+export declare function findOpenFileLeaf<Leaf extends LeafLike>(workspace: OpenFileWorkspaceLike<Leaf>, file: TFile): Leaf | null;
+type LeafViewStateCapture = {
+    state: ViewState;
+    view?: View;
+};
+export declare function captureLeafViewState(leaf: LeafViewStateCapture): ViewState;
+export declare function cloneViewState(state: ViewState): ViewState;
+export declare function historyFilePathForViewState(state: ViewState): string | null;
+export declare function resolveViewForOpenFile(leaf: WorkspaceLeaf, file: TFile, explicitView?: View): View | undefined;
+export declare function applyOpenViewStateToLeaf(leaf: WorkspaceLeaf, openState?: OpenViewState): Promise<void>;
+export {};

package/dist/open-file.js

@@ -0,0 +1,102 @@
+import { ON_DEMAND_PLUGIN_INSTALL_VIEW_TYPE, } from "./workspace.svelte";
+function isFileView(view) {
+    return typeof view.canAcceptExtension === "function";
+}
+function filePathFromView(view) {
+    if (!view || typeof view !== "object" || !("file" in view)) {
+        return null;
+    }
+    const file = view.file;
+    return typeof file?.path === "string" ? file.path : null;
+}
+export function leafFilePath(leaf) {
+    return filePathFromView(leaf?.view);
+}
+export function findOpenFileLeaf(workspace, file) {
+    const focusedHostId = workspace.getFocusedCommandHostId();
+    let fallbackLeaf = null;
+    const matchingLeaf = workspace.iterateAllLeaves((leaf) => {
+        if (leafFilePath(leaf) !== file.path) {
+            return undefined;
+        }
+        if (workspace.getCommandHostIdForLeaf(leaf) === focusedHostId) {
+            return leaf;
+        }
+        fallbackLeaf ??= leaf;
+        return undefined;
+    }) ?? fallbackLeaf;
+    return matchingLeaf ?? null;
+}
+export function captureLeafViewState(leaf) {
+    const view = leaf.view;
+    if (!view) {
+        return cloneViewState(leaf.state);
+    }
+    return cloneViewState({
+        ...leaf.state,
+        type: view.getViewType(),
+        state: {
+            ...(leaf.state.state ?? {}),
+            ...view.getState(),
+        },
+    });
+}
+export function cloneViewState(state) {
+    return {
+        ...state,
+        state: { ...(state.state ?? {}) },
+    };
+}
+const NON_FILE_HISTORY_VIEW_TYPES = new Set(["empty", "graph", "graph-local"]);
+export function historyFilePathForViewState(state) {
+    if (NON_FILE_HISTORY_VIEW_TYPES.has(state.type)) {
+        return null;
+    }
+    const filePath = state.state?.["file"]?.toString();
+    return filePath?.length ? filePath : null;
+}
+export function resolveViewForOpenFile(leaf, file, explicitView) {
+    if (explicitView) {
+        return explicitView;
+    }
+    const currentView = leaf.view;
+    if (currentView &&
+        isFileView(currentView) &&
+        currentView.getViewType() === ON_DEMAND_PLUGIN_INSTALL_VIEW_TYPE &&
+        filePathFromView(currentView) === file.path &&
+        !leaf.app.workspace.viewCreator(file)) {
+        return currentView;
+    }
+    if (currentView &&
+        isFileView(currentView) &&
+        currentView.canAcceptExtension(file.extension)) {
+        const workspace = leaf.app.workspace;
+        const targetViewType = workspace.determineViewTypeForPath(file.path) ??
+            workspace.determineViewType(file.extension);
+        if (targetViewType && currentView.getViewType() === targetViewType) {
+            return currentView;
+        }
+    }
+    return leaf.app.workspace.viewCreator(file)?.(leaf);
+}
+export async function applyOpenViewStateToLeaf(leaf, openState) {
+    if (!openState?.state || Object.keys(openState.state).length === 0) {
+        return;
+    }
+    const view = leaf.view;
+    if (!view || typeof view.setState !== "function") {
+        return;
+    }
+    const mergedState = {
+        ...(typeof view.getState === "function" ? view.getState() : {}),
+        ...openState.state,
+    };
+    await view.setState(mergedState);
+    leaf.state = {
+        ...leaf.state,
+        state: {
+            ...(leaf.state.state ?? {}),
+            ...openState.state,
+        },
+    };
+}