@cocoar/vue-file-explorer-core 2.6.0

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

@@ -0,0 +1,144 @@
+import { MaybeRefOrGetter, Ref } from 'vue';
+import { CoarTreeNodeMoveEvent } from '@cocoar/vue-ui';
+import { CoarScriptEditorLanguage } from '@cocoar/vue-script-editor';
+import { Asset, AssetOp, AssetOpContext, AssetStore, AssetStoreConfig, FileEditor, FileMeta, SortMode } from './asset-store';
+import { AssetProperty } from './describe-asset';
+/**
+ * A tab open in the editor area. Held in `shallowRef` so swaps trigger
+ * re-renders without Vue having to track every keystroke inside `content`.
+ */
+export interface OpenTab {
+    id: string;
+    name: string;
+    editor: FileEditor;
+    language?: CoarScriptEditorLanguage;
+    /** Current editor buffer. */
+    content: string;
+    /** Last persisted content. `content !== savedContent` ⇒ dirty. */
+    savedContent: string;
+    /**
+     * Preview tabs (false) render in italic; opening another file in
+     * preview mode replaces them. Editing auto-promotes to pinned.
+     */
+    pinned: boolean;
+}
+export interface UseFileExplorerOptions<T = unknown> {
+    store: AssetStore<T>;
+    /** Single funnel for every store failure. Composable has already rolled back. */
+    onError?: (op: AssetOp, error: unknown, ctx: AssetOpContext) => void;
+    /** 3-stage fallback override slot (`asset.editor` → here → extension default). */
+    getFileMeta?: AssetStoreConfig<T>['getFileMeta'];
+    /** Discard-dirty / delete confirmations. Default: `window.confirm`. */
+    confirm?: (message: string) => boolean;
+    /** Folder ids to seed `expanded` with. Default: top-level folders. */
+    initialExpandedIds?: readonly string[];
+    /**
+     * Sibling ordering strategy. Default `'folders-first'` (VSCode pattern).
+     * Reactive via `Ref` / getter so a toolbar can swap modes at runtime.
+     * In any non-manual mode the composable silently drops the `position` arg
+     * on `move` — the comparator decides where the moved node lands.
+     */
+    sortMode?: MaybeRefOrGetter<SortMode<T>>;
+}
+export interface UseFileExplorerReturn<T = unknown> {
+    /** Flat reactive asset list (the store's underlying ref). */
+    readonly assets: Readonly<Ref<readonly Asset<T>[]>>;
+    /** Root-level slice — pass directly to `<CoarTree :nodes>`. */
+    readonly rootNodes: Readonly<Ref<readonly Asset<T>[]>>;
+    selectedId: Ref<string | null>;
+    /**
+     * The asset currently selected in the tree, resolved from `selectedId`.
+     * `null` when nothing is selected or the id no longer exists. Drives
+     * details / info panels — pair with `describeAsset`.
+     */
+    readonly selectedAsset: Readonly<Ref<Asset<T> | null>>;
+    expanded: Ref<Set<string>>;
+    getId: (a: Asset<T>) => string;
+    getChildren: (a: Asset<T>) => readonly Asset<T>[] | undefined;
+    getLabel: (a: Asset<T>) => string;
+    isExpandable: (a: Asset<T>) => boolean;
+    /**
+     * `true` when `sortMode === 'manual'`. Reactive so a sort-mode toolbar
+     * can flip it at runtime. Drives whether `move` honors a `position` arg —
+     * future hook for CoarTree's drag mode when the prop is exposed.
+     */
+    readonly reorderable: Readonly<Ref<boolean>>;
+    /**
+     * `true` during the initial `store.loadTree()` call. Stays `false` for
+     * stores that surface their own reactive `_assets` (they own their load
+     * lifecycle). Per-folder lazy loads + per-file content loads live on
+     * `loadingNodes` instead — `loading` is strictly the initial-load signal.
+     */
+    readonly loading: Readonly<Ref<boolean>>;
+    /** Files whose content is being loaded via `store.loadContent`. */
+    readonly loadingNodes: Readonly<Ref<ReadonlySet<string>>>;
+    /** Assets with an in-flight save/rename/delete/move. */
+    readonly savingNodes: Readonly<Ref<ReadonlySet<string>>>;
+    readonly openTabs: Readonly<Ref<readonly OpenTab[]>>;
+    activeId: Ref<string | null>;
+    readonly activeTab: Readonly<Ref<OpenTab | null>>;
+    readonly anyDirty: Readonly<Ref<boolean>>;
+    isDirty: (tab: OpenTab) => boolean;
+    /**
+     * Update a tab's editor buffer. Auto-pins preview tabs the moment they
+     * go dirty (VSCode pattern — dirty preview tabs never exist).
+     */
+    setContent: (id: string, content: string) => void;
+    /** `name` is required — the embedding handles the prompt UI. */
+    addFolder: (parentId: string | null, name: string) => Promise<Asset<T> | null>;
+    addFiles: (parentId: string | null, files: FileList | readonly File[]) => Promise<void>;
+    deleteNode: (asset: Asset<T>) => Promise<void>;
+    /** Translates CoarTree's drop event → `store.move(id, parentId, position?)`. */
+    moveNode: (e: CoarTreeNodeMoveEvent<Asset<T>>) => Promise<void>;
+    rename: (id: string, newName: string) => Promise<void>;
+    /**
+     * Re-fetch the tree (or one folder's children) from the store. No-op for
+     * stores that surface a reactive `_assets` directly — they're already
+     * live. Pass a `folderId` to refresh just that folder in lazy mode;
+     * `undefined` / `null` runs a full `loadTree()`.
+     */
+    refresh: (folderId?: string | null) => Promise<void>;
+    openFile: (asset: Asset<T>, opts?: {
+        pinned: boolean;
+    }) => Promise<void>;
+    /** Pin (`{pinned: true}`); use on dblclick / Enter / "Open" menu item. */
+    activateNode: (asset: Asset<T>) => void;
+    saveTab: (id: string) => Promise<boolean>;
+    saveActive: () => Promise<void>;
+    closeTab: (id: string) => void;
+    closeOthers: (keepId: string) => void;
+    closeToRight: (anchorId: string) => void;
+    closeAll: () => void;
+    pinTab: (id: string) => void;
+    unpinTab: (id: string) => void;
+    /**
+     * Move tab `sourceId` to be immediately `before` or `after` `targetId`
+     * in the tab bar. No-op for self-drop or unknown ids. Pinned vs. preview
+     * status is preserved on the moved tab — consumers that want pinned-only-
+     * left ordering should validate before calling.
+     */
+    reorderTab: (sourceId: string, targetId: string, position: 'before' | 'after') => void;
+    /** Walk parentId chain → expand all ancestors → focus + select. */
+    revealInTree: (id: string, focusNode?: (id: string) => void) => void;
+    /** Asset-name path from root to active file. Empty when no active tab. */
+    readonly breadcrumbPath: Readonly<Ref<readonly string[]>>;
+    /**
+     * Name path from root to `id`, inclusive. Empty when the id isn't found.
+     * Drives breadcrumb-style displays for arbitrary nodes (quick-open,
+     * recent-files, etc.) — `breadcrumbPath` is the active-tab special case.
+     */
+    pathOf: (id: string) => string[];
+    fileMeta: (asset: Asset<T>) => FileMeta | null;
+    /**
+     * Framework-known property rows for an asset — Name, Type, Language
+     * (script files), Extension, and Path — ready to render in a details /
+     * info panel. Returns a fresh array each call. Domain fields that live in
+     * `payload` are the consumer's to append.
+     */
+    describeAsset: (asset: Asset<T>) => AssetProperty[];
+}
+/**
+ * `useFileExplorer<T>(options)` — see file docblock for the contract.
+ */
+export declare function useFileExplorer<T = unknown>(options: UseFileExplorerOptions<T>): UseFileExplorerReturn<T>;
+//# sourceMappingURL=use-file-explorer.d.ts.map

package/dist/use-file-explorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-file-explorer.d.ts","sourceRoot":"","sources":["../src/use-file-explorer.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@cocoar/vue-file-explorer-core",
+  "version": "2.6.0",
+  "description": "VSCode-style file/asset explorer for Vue 3 — composable + types over a pluggable AssetStore<T> backend.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cocoar-dev/cocoar-ui-vue.git",
+    "directory": "packages/file-explorer-core"
+  },
+  "homepage": "https://docs.cocoar.dev/cocoar-ui-vue/",
+  "bugs": "https://github.com/cocoar-dev/cocoar-ui-vue/issues",
+  "keywords": [
+    "vue",
+    "vue3",
+    "file-explorer",
+    "asset-store",
+    "tree"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run --passWithNoTests",
+    "lint": "eslint src/",
+    "typecheck": "vue-tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@cocoar/vue-script-editor": "2.6.0",
+    "@cocoar/vue-ui": "2.6.0",
+    "vue": "^3.5.0"
+  },
+  "peerDependenciesMeta": {
+    "@cocoar/vue-script-editor": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@cocoar/vue-script-editor": "workspace:*",
+    "@cocoar/vue-ui": "workspace:*",
+    "vue": "^3.5.32"
+  }
+}