@lapis-notes/file-explorer 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @lapis-notes/file-explorer
+
+## 0.1.0
+
+### Minor Changes
+
+- First public npm release of the reusable Lapis File Explorer plugin.

package/LICENSE.md

@@ -0,0 +1,4 @@
+AGPL-3.0-or-later
+
+This package is licensed under the GNU Affero General Public License v3.0 or later.
+See <https://www.gnu.org/licenses/agpl-3.0.en.html>.

package/README.md

@@ -0,0 +1,32 @@
+# @lapis-notes/file-explorer
+
+Reusable File Explorer plugin for applications built on the Lapis framework.
+
+The package owns Explorer views, commands, palette entries, and presentation
+settings. Applications retain vault selection, session boot, persistence
+policy, and host integration.
+
+## Public surface
+
+- `FileExplorerPlugin`
+- `createFileExplorerPlugin`
+- `ExplorerPanel`
+- `FileExplorerViewType`
+- `FILE_EXPLORER_SELECTION_CHANGE_EVENT`
+
+## Usage
+
+```ts
+import { FileExplorerPlugin } from "@lapis-notes/file-explorer";
+```
+
+Install `@lapis-notes/api`, `@lapismd/design-core`, and Svelte from npm with
+compatible versions.
+
+## Common scripts
+
+```sh
+pnpm --filter @lapis-notes/file-explorer build
+pnpm --filter @lapis-notes/file-explorer check
+pnpm --filter @lapis-notes/file-explorer test
+```

package/dist/LapisExplorerView.svelte

@@ -0,0 +1,21 @@
+<script lang="ts">
+  import {
+    WorkspaceExplorer,
+    type ExplorerController,
+  } from "@lapismd/design-core/workspace/explorer";
+
+  let { controller }: { controller: ExplorerController } = $props();
+</script>
+
+<div class="lapis-editor-demo-explorer" data-testid="lapis-editor-explorer">
+  <WorkspaceExplorer {controller} />
+</div>
+
+<style>
+  .lapis-editor-demo-explorer {
+    width: 100%;
+    height: 100%;
+    min-width: 0;
+    min-height: 0;
+  }
+</style>

package/dist/LapisExplorerView.svelte.d.ts

@@ -0,0 +1,7 @@
+import { type ExplorerController } from "@lapismd/design-core/workspace/explorer";
+type $$ComponentProps = {
+    controller: ExplorerController;
+};
+declare const LapisExplorerView: import("svelte").Component<$$ComponentProps, {}, "">;
+type LapisExplorerView = ReturnType<typeof LapisExplorerView>;
+export default LapisExplorerView;

package/dist/LapisLandingView.svelte

@@ -0,0 +1,19 @@
+<script lang="ts">
+  import { WorkspaceEmpty } from "@lapismd/design-core/workspace/empty";
+  import type { WorkspaceAction } from "@lapismd/design-core/workspace/core";
+
+  let { actions }: { actions: WorkspaceAction[] } = $props();
+</script>
+
+<div class="lapis-editor-demo-landing" data-testid="lapis-editor-landing">
+  <WorkspaceEmpty {actions} surface="page" />
+</div>
+
+<style>
+  .lapis-editor-demo-landing {
+    width: 100%;
+    height: 100%;
+    min-width: 0;
+    min-height: 0;
+  }
+</style>

package/dist/LapisLandingView.svelte.d.ts

@@ -0,0 +1,7 @@
+import type { WorkspaceAction } from "@lapismd/design-core/workspace/core";
+type $$ComponentProps = {
+    actions: WorkspaceAction[];
+};
+declare const LapisLandingView: import("svelte").Component<$$ComponentProps, {}, "">;
+type LapisLandingView = ReturnType<typeof LapisLandingView>;
+export default LapisLandingView;

package/dist/explorer-selection.d.ts

@@ -0,0 +1,12 @@
+import type { App } from "@lapis-notes/api";
+export declare const FILE_EXPLORER_SELECTION_CHANGE_EVENT = "file-explorer:selection-change";
+export type ExplorerSelectionController = {
+    selectedPath: string;
+    setSelectedPath(path: string): void;
+    selectRoot(): void;
+    revealPath(path: string, options?: {
+        flash?: boolean;
+    }): void;
+};
+export declare function notifyFileExplorerSelection(app: App, path: string): void;
+export declare function bindExplorerSelectionNotifications(app: App, controller: ExplorerSelectionController): void;

package/dist/explorer-selection.js

@@ -0,0 +1,25 @@
+export const FILE_EXPLORER_SELECTION_CHANGE_EVENT = "file-explorer:selection-change";
+function workspaceEvents(app) {
+    return app.workspace;
+}
+export function notifyFileExplorerSelection(app, path) {
+    workspaceEvents(app).trigger(FILE_EXPLORER_SELECTION_CHANGE_EVENT, path);
+}
+export function bindExplorerSelectionNotifications(app, controller) {
+    const notify = () => notifyFileExplorerSelection(app, controller.selectedPath);
+    const setSelectedPath = controller.setSelectedPath.bind(controller);
+    const selectRoot = controller.selectRoot.bind(controller);
+    const revealPath = controller.revealPath.bind(controller);
+    controller.setSelectedPath = (path) => {
+        setSelectedPath(path);
+        notify();
+    };
+    controller.selectRoot = () => {
+        selectRoot();
+        notify();
+    };
+    controller.revealPath = (path, options) => {
+        revealPath(path, options);
+        notify();
+    };
+}

package/dist/explorer-settings.d.ts

@@ -0,0 +1,7 @@
+export declare const EXPLORER_SETTINGS_SECTION_ID = "lapis-file-explorer";
+export declare const EXPLORER_SETTING_IDS: {
+    readonly autoRevealCurrentFile: "workspace.fileExplorer.autoRevealCurrentFile";
+    readonly showHiddenFiles: "workspace.fileExplorer.showHiddenFiles";
+    readonly paletteFileExtensions: "workspace.fileExplorer.paletteFileExtensions";
+};
+export declare const DEFAULT_VAULT_PALETTE_FILE_EXTENSIONS: readonly ["md", "markdown", "txt", "text", "json", "data", "yaml", "yml"];

package/dist/explorer-settings.js

@@ -0,0 +1,16 @@
+export const EXPLORER_SETTINGS_SECTION_ID = "lapis-file-explorer";
+export const EXPLORER_SETTING_IDS = {
+    autoRevealCurrentFile: "workspace.fileExplorer.autoRevealCurrentFile",
+    showHiddenFiles: "workspace.fileExplorer.showHiddenFiles",
+    paletteFileExtensions: "workspace.fileExplorer.paletteFileExtensions",
+};
+export const DEFAULT_VAULT_PALETTE_FILE_EXTENSIONS = [
+    "md",
+    "markdown",
+    "txt",
+    "text",
+    "json",
+    "data",
+    "yaml",
+    "yml",
+];

package/dist/explorer-tree-subscription.d.ts

@@ -0,0 +1,2 @@
+import type { App } from "@lapis-notes/api";
+export declare function subscribeExplorerVaultTreeChanges(app: App, onChange: () => void): () => void;

package/dist/explorer-tree-subscription.js

@@ -0,0 +1,12 @@
+export function subscribeExplorerVaultTreeChanges(app, onChange) {
+    const loaded = app.vault.on("load", onChange);
+    const created = app.vault.on("create", onChange);
+    const deleted = app.vault.on("delete", onChange);
+    const renamed = app.vault.on("rename", onChange);
+    return () => {
+        app.vault.offref(loaded);
+        app.vault.offref(created);
+        app.vault.offref(deleted);
+        app.vault.offref(renamed);
+    };
+}

package/dist/explorer-vault-entries.d.ts

@@ -0,0 +1,5 @@
+import { type TAbstractFile } from "@lapis-notes/api";
+import type { ExplorerNode } from "@lapismd/design-core/workspace/explorer";
+export declare function toExplorerNode(file: TAbstractFile): ExplorerNode;
+/** Pass every vault path except `/`. Hidden-name filtering belongs to Design Core. */
+export declare function listExplorerVaultEntries(files: readonly TAbstractFile[]): ExplorerNode[];

package/dist/explorer-vault-entries.js

@@ -0,0 +1,14 @@
+import { TFolder } from "@lapis-notes/api";
+export function toExplorerNode(file) {
+    return {
+        path: file.path.replace(/^\/+/, ""),
+        name: file.name,
+        kind: file instanceof TFolder ? "folder" : "file",
+    };
+}
+/** Pass every vault path except `/`. Hidden-name filtering belongs to Design Core. */
+export function listExplorerVaultEntries(files) {
+    return files
+        .filter((file) => file.path.replace(/^\/+/, "").length > 0)
+        .map(toExplorerNode);
+}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import { View, type PluginConstructor, type WorkspaceLeaf } from "@lapis-notes/api";
+export declare class FileExplorerView extends View {
+    #private;
+    constructor(leaf: WorkspaceLeaf, loading: boolean);
+    get selectedPath(): string;
+    getViewType(): string;
+    getDisplayText(): string;
+    revealPath(path: string): void;
+    applyShowHiddenFiles(value: boolean): void;
+    load(): void;
+    unload(): void;
+    protected onOpen(): Promise<void>;
+    protected onClose(): Promise<void>;
+}
+export declare class LapisLandingView extends View {
+    #private;
+    getViewType(): string;
+    getDisplayText(): string;
+    load(): void;
+    unload(): void;
+    protected onOpen(): Promise<void>;
+    protected onClose(): Promise<void>;
+}
+export declare function createFileExplorerPlugin(options?: {
+    loading?: boolean;
+}): PluginConstructor;
+export declare const FileExplorerPlugin: PluginConstructor;
+export declare const FileExplorerViewType = "file-explorer";
+export { FILE_EXPLORER_SELECTION_CHANGE_EVENT } from "./explorer-selection";
+export { default as ExplorerPanel } from "./LapisExplorerView.svelte";

package/dist/index.js

@@ -0,0 +1,378 @@
+import { Notice, Plugin, TFile, View, basename, dirname, joinPath, } from "@lapis-notes/api";
+import { getWorkspaceHostBinding } from "@lapis-notes/api/workspace-host";
+import { ExplorerController } from "@lapismd/design-core/workspace/explorer";
+import { mount, unmount } from "svelte";
+import ExplorerPanel from "./LapisExplorerView.svelte";
+import LapisLanding from "./LapisLandingView.svelte";
+import { appendNativeExplorerMenu, copyExplorerText, } from "./native-explorer-actions";
+import { openExplorerFile } from "./open-explorer-file";
+import { DEFAULT_VAULT_PALETTE_FILE_EXTENSIONS, EXPLORER_SETTING_IDS, } from "./explorer-settings";
+import { listExplorerVaultEntries } from "./explorer-vault-entries";
+import { registerExplorerSettings } from "./register-explorer-settings";
+import { subscribeExplorerVaultTreeChanges } from "./explorer-tree-subscription";
+import { listVaultPaletteFiles, VAULT_PALETTE_FILES_TAB, VAULT_PALETTE_RECENT_GROUP, } from "./vault-palette-files";
+import { bindExplorerSelectionNotifications } from "./explorer-selection";
+const EXPLORER_MANIFEST = {
+    id: "lapis-file-explorer",
+    name: "Explorer",
+    author: "Lapis Notes",
+    version: "0.1.0",
+    minAppVersion: "0.0.1",
+    description: "Lapis file explorer backed by the API vault.",
+};
+const EXPLORER_SCHEMA = {
+    id: "workspace",
+    title: "Workspace",
+    type: "object",
+    properties: {
+        [EXPLORER_SETTING_IDS.autoRevealCurrentFile]: {
+            title: "Auto-reveal current file",
+            description: "Reveal the active file in Explorer.",
+            type: "boolean",
+            default: true,
+        },
+        [EXPLORER_SETTING_IDS.showHiddenFiles]: {
+            title: "Show hidden files",
+            description: "Show dotted names, including .obsidian, .trash, and .lapis.",
+            type: "boolean",
+            default: false,
+        },
+        [EXPLORER_SETTING_IDS.paletteFileExtensions]: {
+            title: "File palette extensions",
+            description: "Extensions shown by Go to file, without leading dots. An empty list hides every file from the Files palette.",
+            type: "array",
+            items: { type: "string" },
+            default: [...DEFAULT_VAULT_PALETTE_FILE_EXTENSIONS],
+        },
+    },
+};
+function readShowHiddenFiles(app) {
+    return app.configuration
+        .getConfiguration()
+        .get(EXPLORER_SETTING_IDS.showHiddenFiles, false);
+}
+function displayError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function parentPath(path) {
+    const parent = dirname(path);
+    return parent === "/" ? "" : parent;
+}
+async function uniquePath(app, parent, requestedName) {
+    const dot = requestedName.lastIndexOf(".");
+    const base = dot > 0 ? requestedName.slice(0, dot) : requestedName;
+    const extension = dot > 0 ? requestedName.slice(dot) : "";
+    for (let suffix = 0;; suffix += 1) {
+        const name = `${base}${suffix === 0 ? "" : ` ${suffix + 1}`}${extension}`;
+        const path = parent ? joinPath(parent, name) : name;
+        if (!(await app.vault.exists(path)))
+            return path;
+    }
+}
+async function withNotice(operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        new Notice(displayError(error));
+        throw error;
+    }
+}
+function createExplorerController(app, loading) {
+    const controller = new ExplorerController({
+        loading,
+        tree: {
+            listEntries: () => listExplorerVaultEntries(app.vault.getAllLoadedFiles()),
+            subscribe: (onChange) => subscribeExplorerVaultTreeChanges(app, onChange),
+        },
+        selection: {
+            subscribe: (onActivePath) => {
+                // Dedupe so breadcrumb/folder revealPath is not immediately overwritten
+                // when focus moves within the same active file leaf.
+                let lastPath;
+                const update = () => {
+                    const path = app.workspace.activeEditor?.file?.path ?? null;
+                    if (path === lastPath)
+                        return;
+                    lastPath = path;
+                    onActivePath(path);
+                };
+                const ref = app.workspace.on("active-leaf-change", update);
+                update();
+                return () => app.workspace.offref(ref);
+            },
+        },
+        preferences: {
+            getAutoReveal: () => app.configuration
+                .getConfiguration()
+                .get(EXPLORER_SETTING_IDS.autoRevealCurrentFile, true),
+            setAutoReveal: (value) => app.configuration.updateConfigurationOption(EXPLORER_SETTING_IDS.autoRevealCurrentFile, value),
+            getShowHiddenFiles: () => readShowHiddenFiles(app),
+            setShowHiddenFiles: (value) => app.configuration.updateConfigurationOption(EXPLORER_SETTING_IDS.showHiddenFiles, value),
+        },
+        actions: {
+            openFile: (path, options) => withNotice(async () => {
+                const file = app.vault.getFileByPath(path);
+                if (!file)
+                    throw new Error(`Unable to find file: ${path}`);
+                await openExplorerFile(app, file, options?.disposition ?? "current");
+            }),
+            createFile: (parent) => withNotice(async () => {
+                const path = await uniquePath(app, parent, "Untitled.md");
+                const file = await app.vault.create(path, "");
+                await app.openFile(file);
+                return path;
+            }),
+            createFolder: (parent) => withNotice(async () => {
+                const path = await uniquePath(app, parent, "New folder");
+                await app.vault.createFolder(path);
+                return path;
+            }),
+            rename: (path, nextName) => withNotice(async () => {
+                const file = app.vault.getAbstractFileByPath(path);
+                if (!file)
+                    throw new Error(`Unable to find path: ${path}`);
+                const nextPath = joinPath(parentPath(path), nextName);
+                if (await app.vault.exists(nextPath)) {
+                    throw new Error(`A file already exists at ${nextPath}`);
+                }
+                await app.fileManager.renameFile(file, nextPath);
+                return nextPath;
+            }),
+            move: (path, destinationFolderPath) => withNotice(async () => {
+                const file = app.vault.getAbstractFileByPath(path);
+                if (!file)
+                    throw new Error(`Unable to find path: ${path}`);
+                const nextPath = joinPath(destinationFolderPath, basename(path));
+                if (await app.vault.exists(nextPath)) {
+                    throw new Error(`A file already exists at ${nextPath}`);
+                }
+                await app.fileManager.renameFile(file, nextPath);
+                return nextPath;
+            }),
+            delete: (path) => withNotice(async () => {
+                const file = app.vault.getAbstractFileByPath(path);
+                if (!file)
+                    throw new Error(`Unable to find path: ${path}`);
+                await app.vault.trash(file, false);
+            }),
+            copyText: copyExplorerText,
+        },
+        buildItemMenu: (menu, node) => {
+            appendNativeExplorerMenu(menu, node, app);
+        },
+    });
+    bindExplorerSelectionNotifications(app, controller);
+    return controller;
+}
+export class FileExplorerView extends View {
+    #controller;
+    #component = null;
+    constructor(leaf, loading) {
+        super(leaf);
+        this.icon = "folder-closed";
+        this.#controller = createExplorerController(this.app, loading);
+    }
+    get selectedPath() {
+        return this.#controller.selectedPath;
+    }
+    getViewType() {
+        return "file-explorer";
+    }
+    getDisplayText() {
+        return "Files";
+    }
+    revealPath(path) {
+        this.#controller.revealPath(path.replace(/^\/+/, ""));
+    }
+    applyShowHiddenFiles(value) {
+        this.#controller.applyShowHiddenFiles(value);
+    }
+    load() {
+        this.unload();
+        this.containerEl.replaceChildren();
+        this.#component = mount(ExplorerPanel, {
+            target: this.containerEl,
+            props: { controller: this.#controller },
+        });
+    }
+    unload() {
+        if (this.#component)
+            void unmount(this.#component);
+        this.#component = null;
+    }
+    onOpen() {
+        return Promise.resolve();
+    }
+    onClose() {
+        return Promise.resolve();
+    }
+}
+function isFileExplorerView(view) {
+    return view instanceof FileExplorerView;
+}
+export class LapisLandingView extends View {
+    #component = null;
+    getViewType() {
+        return "lapis-landing";
+    }
+    getDisplayText() {
+        return "New tab";
+    }
+    load() {
+        this.unload();
+        this.containerEl.replaceChildren();
+        const actions = [
+            {
+                id: "create-note",
+                label: "Create new note",
+                icon: "square-pen",
+                onSelect: async () => {
+                    const path = await uniquePath(this.app, "", "Untitled.md");
+                    const file = await this.app.vault.create(path, "");
+                    await this.app.openFile(file);
+                },
+            },
+            {
+                id: "go-to-file",
+                label: "Go to file",
+                icon: "search",
+                onSelect: () => {
+                    void this.app.commands.executeCommand("app:go-to-file");
+                },
+            },
+            {
+                id: "close",
+                label: "Close",
+                icon: "x",
+                onSelect: () => {
+                    this.leaf.detach();
+                },
+            },
+        ];
+        this.#component = mount(LapisLanding, {
+            target: this.containerEl,
+            props: { actions },
+        });
+    }
+    unload() {
+        if (this.#component)
+            void unmount(this.#component);
+        this.#component = null;
+    }
+    onOpen() {
+        return Promise.resolve();
+    }
+    onClose() {
+        return Promise.resolve();
+    }
+}
+export function createFileExplorerPlugin(options = {}) {
+    return class FileExplorerPlugin extends Plugin {
+        constructor(app) {
+            super(app, EXPLORER_MANIFEST);
+        }
+        async onload() {
+            this.app.configuration.schema.register(EXPLORER_SCHEMA);
+            this.register(() => {
+                this.app.configuration.schema.unregister(EXPLORER_SCHEMA);
+            });
+            registerExplorerSettings(this);
+            const configurationRef = this.app.configuration.on("updated", ({ key, value }) => {
+                if (key !== EXPLORER_SETTING_IDS.showHiddenFiles)
+                    return;
+                this.syncShowHiddenFiles(Boolean(value));
+            });
+            this.register(() => {
+                this.app.configuration.offref(configurationRef);
+            });
+            this.registerSidebarView(FileExplorerViewType, (leaf) => new FileExplorerView(leaf, options.loading ?? false), {
+                side: "left",
+                title: "Files",
+                icon: "folder-closed",
+            }, {
+                kind: "command",
+                command: {
+                    id: "open-explorer",
+                    name: "Open Explorer",
+                    callback: () => void this.openExplorer(),
+                },
+            });
+            this.registerView("lapis-landing", (leaf) => new LapisLandingView(leaf), {
+                kind: "internal",
+            });
+            this.addCommand({
+                id: "reveal-path",
+                name: "Reveal path in file explorer",
+                callback: (path) => {
+                    if (typeof path !== "string" || path.length === 0)
+                        return;
+                    this.app.workspace.iterateAllLeaves((leaf) => {
+                        if (!isFileExplorerView(leaf.view))
+                            return;
+                        leaf.view.revealPath(path);
+                    });
+                },
+            });
+            this.addCommand({
+                id: "toggle-hidden-files",
+                name: "Toggle show hidden files",
+                callback: () => {
+                    void this.app.configuration.updateConfigurationOption(EXPLORER_SETTING_IDS.showHiddenFiles, !readShowHiddenFiles(this.app));
+                },
+            });
+            const { controller } = getWorkspaceHostBinding(this.app.workspace);
+            this.register(controller.commands.registerPaletteProvider({
+                id: "lapis-vault-files",
+                tab: VAULT_PALETTE_FILES_TAB,
+                emptyQueryLimit: 5,
+                search: (query) => {
+                    const starterFiles = query.trim().length === 0;
+                    const recentPaths = starterFiles
+                        ? new Set(this.app.workspace
+                            .getRecentFiles()
+                            .map((recent) => recent.path))
+                        : null;
+                    return listVaultPaletteFiles(this.app, query).map((file) => ({
+                        id: `vault-file:${file.path}`,
+                        title: file.name,
+                        subtitle: file.path,
+                        icon: "file",
+                        providerId: "lapis-vault-files",
+                        tab: VAULT_PALETTE_FILES_TAB.id,
+                        group: recentPaths?.has(file.path)
+                            ? VAULT_PALETTE_RECENT_GROUP
+                            : undefined,
+                        run: () => this.app.openFile(file),
+                    }));
+                },
+            }));
+            await this.app.configuration.materializeSchemaDefaults();
+        }
+        syncShowHiddenFiles(value) {
+            this.app.workspace.iterateAllLeaves((leaf) => {
+                if (!isFileExplorerView(leaf.view))
+                    return;
+                leaf.view.applyShowHiddenFiles(value);
+            });
+        }
+        async openExplorer() {
+            const existing = this.app.workspace.getLeavesOfType(FileExplorerViewType)[0];
+            const target = existing ??
+                this.app.workspace.ensureSideLeaf(FileExplorerViewType, "left");
+            if (!existing) {
+                await target.setViewState({ type: FileExplorerViewType, state: {} });
+            }
+            this.app.workspace.activateLeaf(target, {
+                focusRootHost: false,
+                source: "api",
+                operation: "open-explorer",
+            });
+            await this.app.workspace.revealLeaf(target);
+        }
+    };
+}
+export const FileExplorerPlugin = createFileExplorerPlugin();
+export const FileExplorerViewType = "file-explorer";
+export { FILE_EXPLORER_SELECTION_CHANGE_EVENT } from "./explorer-selection";
+export { default as ExplorerPanel } from "./LapisExplorerView.svelte";

package/dist/native-explorer-actions.d.ts

@@ -0,0 +1,8 @@
+import { type App } from "@lapis-notes/api";
+import { NativeDesktopVaultAdapter, type NativeDesktopPlatformOs } from "@lapis-notes/api/desktop-native";
+import type { ExplorerNode } from "@lapismd/design-core/workspace/explorer";
+import type { WorkspaceMenu } from "@lapismd/design-core/workspace/core";
+export declare function hasNativeExplorerActions(adapter: App["vault"]["adapter"]): adapter is NativeDesktopVaultAdapter;
+export declare function revealInFileManagerLabel(os: NativeDesktopPlatformOs | undefined): string;
+export declare function copyExplorerText(label: string, value: string): Promise<void>;
+export declare function appendNativeExplorerMenu(menu: WorkspaceMenu, node: ExplorerNode, app: App): void;

package/dist/native-explorer-actions.js

@@ -0,0 +1,74 @@
+import { createLapisFileUrl, Notice } from "@lapis-notes/api";
+import { getNativeDesktopPlatform, hasNativeDesktopCapability, NativeDesktopVaultAdapter, openNativeDesktopVaultPath, resolveNativeDesktopVaultPath, revealNativeDesktopVaultPath, } from "@lapis-notes/api/desktop-native";
+export function hasNativeExplorerActions(adapter) {
+    return (adapter instanceof NativeDesktopVaultAdapter &&
+        hasNativeDesktopCapability("file-system-actions"));
+}
+export function revealInFileManagerLabel(os) {
+    if (os === "macos")
+        return "Reveal in Finder";
+    if (os === "windows")
+        return "Reveal in File Explorer";
+    return "Reveal in file manager";
+}
+export async function copyExplorerText(label, value) {
+    if (typeof navigator !== "undefined" && navigator.clipboard?.writeText) {
+        await navigator.clipboard.writeText(value);
+    }
+    new Notice(`Copied ${label}`);
+}
+function vaultPath(node) {
+    return node.path === "/" ? "/" : node.path;
+}
+export function appendNativeExplorerMenu(menu, node, app) {
+    const adapter = app.vault.adapter;
+    if (!hasNativeExplorerActions(adapter))
+        return;
+    const copyPath = menu.entries.find((entry) => entry.kind === "submenu" && entry.title === "Copy Path");
+    if (copyPath?.kind === "submenu") {
+        copyPath.menu.addItem((item) => item.setTitle("From system root").onClick(() => {
+            void copySystemRootPath(adapter, node);
+        }));
+        if (node.kind === "file") {
+            copyPath.menu.addItem((item) => item.setTitle("As Lapis URL").onClick(() => {
+                void copyExplorerText("Lapis URL", createLapisFileUrl(app.vault.getName(), vaultPath(node)));
+            }));
+        }
+    }
+    menu.addSeparator();
+    menu.addItem((item) => item.setTitle("Open in default app").onClick(() => {
+        void openVaultPath(adapter, node);
+    }));
+    menu.addItem((item) => item
+        .setTitle(revealInFileManagerLabel(getNativeDesktopPlatform()?.os))
+        .onClick(() => {
+        void revealVaultPath(adapter, node);
+    }));
+}
+async function copySystemRootPath(adapter, node) {
+    try {
+        const absolute = await resolveNativeDesktopVaultPath(adapter.rootPath, vaultPath(node));
+        if (!absolute)
+            throw new Error("Unable to resolve the system path");
+        await copyExplorerText("system path", absolute);
+    }
+    catch (error) {
+        new Notice(error instanceof Error ? error.message : String(error));
+    }
+}
+async function openVaultPath(adapter, node) {
+    try {
+        await openNativeDesktopVaultPath(adapter.rootPath, vaultPath(node));
+    }
+    catch (error) {
+        new Notice(error instanceof Error ? error.message : String(error));
+    }
+}
+async function revealVaultPath(adapter, node) {
+    try {
+        await revealNativeDesktopVaultPath(adapter.rootPath, vaultPath(node));
+    }
+    catch (error) {
+        new Notice(error instanceof Error ? error.message : String(error));
+    }
+}

package/dist/open-explorer-file.d.ts

@@ -0,0 +1,3 @@
+import { type App, type TFile } from "@lapis-notes/api";
+import type { ExplorerOpenDisposition } from "@lapismd/design-core/workspace/explorer";
+export declare function openExplorerFile(app: App, file: TFile, disposition: ExplorerOpenDisposition): Promise<void>;

package/dist/open-explorer-file.js

@@ -0,0 +1,20 @@
+import { findOpenFileLeaf, } from "@lapis-notes/api";
+export async function openExplorerFile(app, file, disposition) {
+    if (disposition === "current") {
+        await app.openFile(file);
+        return;
+    }
+    if (disposition === "reveal-or-new-tab") {
+        const existingLeaf = findOpenFileLeaf(app.workspace, file);
+        if (existingLeaf) {
+            app.workspace.activateLeaf(existingLeaf, {
+                operation: "open-explorer-existing-file",
+            });
+            return;
+        }
+    }
+    const leaf = app.workspace.getLeaf("tab");
+    app.workspace.activeLeaf = leaf;
+    await leaf.openFile(file);
+    await app.workspace.revealLeaf(leaf);
+}

package/dist/register-explorer-settings.d.ts

@@ -0,0 +1,33 @@
+import type { Plugin } from "@lapis-notes/api";
+export declare function createExplorerSettingsSection(): {
+    id: string;
+    title: string;
+    description: string;
+    icon: "folder-closed";
+    order: number;
+    navigationGroupId: string;
+    sourcePluginId: string;
+    fields: ({
+        id: "workspace.fileExplorer.autoRevealCurrentFile";
+        type: "boolean";
+        title: string;
+        description: string;
+        default: boolean;
+        itemType?: undefined;
+    } | {
+        id: "workspace.fileExplorer.showHiddenFiles";
+        type: "boolean";
+        title: string;
+        description: string;
+        default: boolean;
+        itemType?: undefined;
+    } | {
+        id: "workspace.fileExplorer.paletteFileExtensions";
+        type: "list";
+        itemType: "string";
+        title: string;
+        description: string;
+        default: ("text" | "data" | "md" | "markdown" | "txt" | "json" | "yaml" | "yml")[];
+    })[];
+};
+export declare function registerExplorerSettings(plugin: Plugin): void;

package/dist/register-explorer-settings.js

@@ -0,0 +1,45 @@
+import { getWorkspaceHostBinding } from "@lapis-notes/api/workspace-host";
+import { DEFAULT_VAULT_PALETTE_FILE_EXTENSIONS, EXPLORER_SETTING_IDS, EXPLORER_SETTINGS_SECTION_ID, } from "./explorer-settings";
+export function createExplorerSettingsSection() {
+    return {
+        id: EXPLORER_SETTINGS_SECTION_ID,
+        title: "Explorer",
+        description: "File tree reveal, visibility, and file-palette behavior.",
+        icon: "folder-closed",
+        order: 22,
+        navigationGroupId: "core-plugins",
+        sourcePluginId: "lapis-file-explorer",
+        fields: [
+            {
+                id: EXPLORER_SETTING_IDS.autoRevealCurrentFile,
+                type: "boolean",
+                title: "Auto-reveal current file",
+                description: "Reveal the active file in Explorer.",
+                default: true,
+            },
+            {
+                id: EXPLORER_SETTING_IDS.showHiddenFiles,
+                type: "boolean",
+                title: "Show hidden files",
+                description: "Show dotted names, including .obsidian, .trash, and .lapis.",
+                default: false,
+            },
+            {
+                id: EXPLORER_SETTING_IDS.paletteFileExtensions,
+                type: "list",
+                itemType: "string",
+                title: "File palette extensions",
+                description: "Extensions shown by Go to file, without leading dots. An empty list hides every file from the Files palette.",
+                default: [...DEFAULT_VAULT_PALETTE_FILE_EXTENSIONS],
+            },
+        ],
+    };
+}
+export function registerExplorerSettings(plugin) {
+    if (!plugin.app.workspace)
+        return;
+    const binding = getWorkspaceHostBinding(plugin.app.workspace);
+    if (!binding)
+        return;
+    plugin.register(binding.controller.registerSettingsSection(createExplorerSettingsSection()));
+}

package/dist/vault-palette-files.d.ts

@@ -0,0 +1,9 @@
+import type { App, TFile } from "@lapis-notes/api";
+export declare const VAULT_PALETTE_FILES_TAB: {
+    readonly id: "files";
+    readonly label: "Files";
+    readonly order: 20;
+};
+export declare const VAULT_PALETTE_RECENT_GROUP = "Recent";
+export declare const VAULT_PALETTE_EMPTY_QUERY_LIMIT = 25;
+export declare function listVaultPaletteFiles(app: App, query: string): TFile[];

package/dist/vault-palette-files.js

@@ -0,0 +1,53 @@
+import { DEFAULT_VAULT_PALETTE_FILE_EXTENSIONS, EXPLORER_SETTING_IDS, } from "./explorer-settings";
+import { isVisibleExplorerPath } from "./vault-path-visibility";
+export const VAULT_PALETTE_FILES_TAB = {
+    id: "files",
+    label: "Files",
+    order: 20,
+};
+export const VAULT_PALETTE_RECENT_GROUP = "Recent";
+export const VAULT_PALETTE_EMPTY_QUERY_LIMIT = 25;
+function readShowHiddenFiles(app) {
+    return app.configuration
+        .getConfiguration()
+        .get(EXPLORER_SETTING_IDS.showHiddenFiles, false);
+}
+function readPaletteFileExtensions(app) {
+    const configured = app.configuration
+        .getConfiguration()
+        .get(EXPLORER_SETTING_IDS.paletteFileExtensions, [
+        ...DEFAULT_VAULT_PALETTE_FILE_EXTENSIONS,
+    ]);
+    if (!Array.isArray(configured)) {
+        return new Set(DEFAULT_VAULT_PALETTE_FILE_EXTENSIONS);
+    }
+    return new Set(configured
+        .filter((extension) => typeof extension === "string")
+        .map((extension) => extension.trim().replace(/^\.+/, "").toLowerCase())
+        .filter(Boolean));
+}
+function isPaletteVisibleFile(file, showHiddenFiles, paletteFileExtensions) {
+    return (isVisibleExplorerPath(file.path, {
+        showHidden: showHiddenFiles,
+    }) && paletteFileExtensions.has(file.extension.toLowerCase()));
+}
+export function listVaultPaletteFiles(app, query) {
+    const normalized = query.trim().toLocaleLowerCase();
+    const showHiddenFiles = readShowHiddenFiles(app);
+    const paletteFileExtensions = readPaletteFileExtensions(app);
+    const isVisible = (file) => isPaletteVisibleFile(file, showHiddenFiles, paletteFileExtensions);
+    if (!normalized) {
+        const recent = app.workspace
+            .getRecentFiles()
+            .filter(isVisible)
+            .slice(0, VAULT_PALETTE_EMPTY_QUERY_LIMIT);
+        if (recent.length > 0)
+            return recent;
+    }
+    return app.vault
+        .getFiles()
+        .filter(isVisible)
+        .filter((file) => file.path.toLocaleLowerCase().includes(normalized))
+        .sort((left, right) => left.path.localeCompare(right.path))
+        .slice(0, normalized ? undefined : VAULT_PALETTE_EMPTY_QUERY_LIMIT);
+}

package/dist/vault-path-visibility.d.ts

@@ -0,0 +1,4 @@
+export declare function isHiddenExplorerPath(path: string): boolean;
+export declare function isVisibleExplorerPath(path: string, options?: {
+    showHidden?: boolean;
+}): boolean;

package/dist/vault-path-visibility.js

@@ -0,0 +1,9 @@
+export function isHiddenExplorerPath(path) {
+    return path
+        .replace(/^\/+/, "")
+        .split("/")
+        .some((segment) => segment.startsWith("."));
+}
+export function isVisibleExplorerPath(path, options = {}) {
+    return options.showHidden === true || !isHiddenExplorerPath(path);
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@lapis-notes/file-explorer",
+  "version": "0.1.0",
+  "description": "Reusable Lapis Notes file explorer plugin",
+  "license": "AGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lapismd/lapis-notes.git",
+    "directory": "packages/file-explorer"
+  },
+  "homepage": "https://github.com/lapismd/lapis-notes/tree/main/packages/file-explorer#readme",
+  "bugs": {
+    "url": "https://github.com/lapismd/lapis-notes/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "files": [
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE.md",
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/*.spec.*"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "svelte": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@lapis-notes/api": "^0.1.0",
+    "@lapismd/design-core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "svelte": "^5.0.0"
+  },
+  "devDependencies": {
+    "@sveltejs/package": "^2.5.0",
+    "@sveltejs/vite-plugin-svelte": "^5.1.1",
+    "@tsconfig/svelte": "^5.0.5",
+    "publint": "^0.3.12",
+    "svelte": "^5.38.2",
+    "svelte-check": "^4.3.1",
+    "typescript": "~5.8.3",
+    "vite": "^6.4.2",
+    "vitest": "^4.1.8"
+  },
+  "scripts": {
+    "build": "pnpm run prepack",
+    "check": "pnpm --dir ../.. check:no-tailwind packages/file-explorer/src && pnpm check:svelte && pnpm check:types",
+    "check:svelte": "svelte-check --tsconfig ./tsconfig.app.json --fail-on-warnings --output human",
+    "check:types": "tsc -p tsconfig.node.json --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}