@cocoar/vue-file-explorer-core 2.6.0

package/README.md

@@ -0,0 +1,121 @@
+# @cocoar/vue-file-explorer-core
+
+VSCode-style file/asset explorer for Vue 3 — a single composable + a pluggable `AssetStore<T>` contract that decouples the UX from your backend (HTTP, IndexedDB, in-memory, whatever).
+
+> **Status: Preview tier.** API is stable enough to consume, but small tweaks may land before the Preview marker drops. Full VitePress reference + live demos coming soon.
+
+## Install
+
+```bash
+pnpm add @cocoar/vue-file-explorer-core @cocoar/vue-ui
+```
+
+`@cocoar/vue-ui` (for `CoarTree` + `CoarTreeNodeLabel`) is the only required peer. `@cocoar/vue-script-editor` is optional — it's only pulled if you want the resolver's Monaco-language-typed `language` field on `FileMeta`.
+
+## What you get
+
+| Piece | Role |
+|---|---|
+| `AssetStore<T>` | The data-plane contract a backend implements (load, mutate, conflict-resolve). |
+| `createInMemoryAssetStore` | Default impl with reactive latency / failure / sortMode / lazy / conflict knobs — perfect for demos, tests, and rapid prototyping. |
+| `useFileExplorer({store})` | The composable. Owns tree + tab state machine, async-loading bookkeeping, blob-URL leases, `beforeunload` warning, keyboard-driven UX. Returns refs to bind to `<CoarTree>` plus ops to call on user input. |
+| `defaultFileMetaFromName` + `resolveFileMeta` | 3-stage fallback (`asset.editor` → `config.getFileMeta` → extension heuristic) that picks an editor + language for every file. Extension table covers ~40 Monaco-supported languages plus markdown / PDF / image. |
+
+## Quick start
+
+```ts
+import {
+  createInMemoryAssetStore,
+  useFileExplorer,
+  type Asset,
+} from '@cocoar/vue-file-explorer-core';
+
+const seed: Asset[] = [
+  { id: 'src',     name: 'src',     kind: 'folder', parentId: null  },
+  { id: 'utils',   name: 'utils.ts', kind: 'file', parentId: 'src'  },
+  { id: 'docs',    name: 'docs',    kind: 'folder', parentId: null  },
+  { id: 'readme',  name: 'README.md', kind: 'file', parentId: 'docs' },
+];
+const store = createInMemoryAssetStore({
+  initialTree: seed,
+  initialContent: {
+    utils:  `export function clamp(...){}`,
+    readme: `# Hello`,
+  },
+});
+
+const fe = useFileExplorer({
+  store,
+  onError: (op, err, ctx) => console.warn(`[file-explorer] ${op}:`, err, ctx),
+});
+```
+
+Then bind into `<CoarTree>` and your own tab bar + editor dispatch:
+
+```vue
+<CoarTree
+  :nodes="fe.rootNodes.value"
+  :get-id="fe.getId"
+  :get-children="fe.getChildren"
+  :get-label="fe.getLabel"
+  :is-expandable="fe.isExpandable"
+  v-model:expanded="fe.expanded.value"
+  v-model:selected="fe.selectedId.value"
+  draggable
+  renamable
+  @activate="fe.activateNode"
+  @rename="({node, newName}) => fe.rename(node.id, newName)"
+  @node-move="fe.moveNode"
+>
+  <template #default="{ node }">
+    <CoarIcon :name="node.kind === 'folder' ? 'folder' : 'file'" />
+    <CoarTreeNodeLabel :label="node.name" />
+  </template>
+</CoarTree>
+```
+
+The composable also returns `openTabs`, `activeTab`, `breadcrumbPath`, `loadingNodes`, `savingNodes`, `pathOf`, plus imperative ops `openFile` / `saveTab` / `closeTab` / `pinTab` / `unpinTab` / `reorderTab` / `addFolder` / `addFiles` / `deleteNode` / `setContent` / `refresh`.
+
+## Wiring your own backend
+
+Implement the `AssetStore<T>` methods — `createAssetStore(config)` returns the typed store:
+
+```ts
+import { createAssetStore, type AssetStore } from '@cocoar/vue-file-explorer-core';
+
+interface MyAsset { mimeType: string; size: number }
+
+const store: AssetStore<MyAsset> = createAssetStore({
+  async loadTree() {
+    return (await fetch('/api/assets').then(r => r.json())) as Asset<MyAsset>[];
+  },
+  async loadContent(id) { return await fetch(`/api/assets/${id}`).then(r => r.text()); },
+  async createFolder(parentId, name) { /* … */ },
+  async createFile(parentId, name)   { /* … */ },
+  async uploadFile(parentId, file)   { /* … */ },
+  async save(id, content)            { /* … */ },
+  async rename(id, newName)          { /* … */ },
+  async delete(id)                   { /* … */ },
+  async move(id, parentId, position?) { /* … */ },
+  // optional — opt into lazy loading
+  async loadChildren(parentId)       { /* … */ },
+  onError: (op, err, ctx) => myToast.error(err.message),
+  getFileMeta: (asset) => asset.payload?.mimeType === 'application/pdf'
+    ? { editor: 'pdf' }
+    : null,
+});
+```
+
+The composable's behavior is identical for any store implementation — eager / lazy mode is detected from the presence of `loadChildren`.
+
+## v1 scope
+
+- ✅ `AssetStore<T>` contract + `createAssetStore` passthrough + `createInMemoryAssetStore` reference impl
+- ✅ Lazy mode (`loadChildren` opt-in)
+- ✅ Sort modes: `'folders-first'` (default), `'alphabetical'`, `'manual'`, custom comparator
+- ✅ Conflict policy: `'rename'` (default), `'overwrite'`, `'prompt'`, `'error'`, custom function
+- ✅ Tab state machine: preview / pinned, auto-pin-on-edit, dirty marker, save flow, drag-to-reorder
+- ✅ Composable-driven inline rename via `CoarTree :renamable` + `CoarTreeNodeLabel`
+- ✅ Error funnel via single `onError(op, err, ctx)` callback
+- ❌ `<CoarFileExplorer>` wrapper component — for v1, consumers compose the shell themselves (see the playground POC for a 1280-LoC worked example). A wrapper is a candidate for v2 once the API surface settles.
+- ❌ Split-pane editors, find-in-files, ETag / optimistic-conflict — deferred to post-v1.

package/dist/asset-store.d.ts

@@ -0,0 +1,284 @@
+import { CoarScriptEditorLanguage } from '@cocoar/vue-script-editor';
+import { Ref } from 'vue';
+/**
+ * Which built-in editor renders an asset.
+ *   - `script`   — `<CoarScriptEditor>` (Monaco); `language` picks the grammar.
+ *   - `markdown` — `<CoarMarkdownEditor>` (Milkdown WYSIWYG).
+ *   - `pdf`      — `<CoarDocumentViewer>` with `pdfSource()`.
+ *   - `image`    — `<CoarDocumentViewer>` with `imageSource()`.
+ */
+export type FileEditor = 'script' | 'markdown' | 'pdf' | 'image';
+/** Editor dispatch metadata for one file. */
+export interface FileMeta {
+    editor: FileEditor;
+    /** Only meaningful when `editor === 'script'`. */
+    language?: CoarScriptEditorLanguage;
+}
+/**
+ * The canonical shape the file-explorer works with.
+ *
+ * Hierarchy + name + kind live at the top level — the framework needs them.
+ * `payload` is the consumer's bag of domain data, fully generic.
+ *
+ * `editor` / `language` are optional escape hatches: when present they win
+ * over `config.getFileMeta` and the extension-based default.
+ */
+export interface Asset<T = unknown> {
+    id: string;
+    name: string;
+    kind: 'folder' | 'file';
+    parentId: string | null;
+    /**
+     * Lazy-load hint. When present and the store implements `loadChildren`,
+     * the folder renders as expandable even before its children are fetched.
+     * Ignored in eager mode.
+     */
+    hasChildren?: boolean;
+    editor?: FileEditor;
+    language?: CoarScriptEditorLanguage;
+    /** Consumer's domain payload — anything not in the framework's contract. */
+    payload?: T;
+}
+/**
+ * What to do with the conflict the policy resolved.
+ *
+ *   - `'overwrite'`         — replace the existing entry; the store recursively
+ *                             deletes it and then performs the create/upload.
+ *   - `'rename'` + newName  — create with the supplied alternative name.
+ *   - `'cancel'`            — abort the op; the store throws a conflict error.
+ */
+export type ConflictResolution = {
+    action: 'overwrite';
+} | {
+    action: 'rename';
+    newName: string;
+} | {
+    action: 'cancel';
+};
+/** Context handed to a function-shaped policy so it can build a smart response. */
+export interface ConflictInfo<T = unknown> {
+    /** The colliding existing asset. */
+    existing: Asset<T>;
+    /** What the caller asked to add (name + kind only — no id yet). */
+    incoming: {
+        name: string;
+        kind: 'folder' | 'file';
+    };
+    /** Where the new entry would have lived. */
+    parentId: string | null;
+    /** Auto-rename candidate ("foo.txt" → "foo (2).txt"). */
+    suggestedRename: string;
+}
+/**
+ * How the store should handle a sibling-name collision on create / upload.
+ * Default: `'rename'` (silent auto-suffix — matches macOS Finder / VSCode).
+ *
+ *   - `'rename'`    — auto-rename: "foo.txt" → "foo (2).txt", etc.
+ *   - `'overwrite'` — delete the existing entry (recursively) and proceed.
+ *   - `'prompt'`    — `window.prompt` for an alternative name, default to
+ *                     the auto-rename suggestion. Cancel → throws conflict.
+ *   - `'error'`     — never resolve; always throw the conflict error.
+ *   - `(info) => …` — custom resolver; sync or async.
+ *
+ * `move` and `rename` deliberately bypass the policy — they're explicit
+ * user intent, not file additions, so silently changing the requested
+ * name would be surprising.
+ */
+export type ConflictPolicy<T = unknown> = 'rename' | 'overwrite' | 'prompt' | 'error' | ((info: ConflictInfo<T>) => ConflictResolution | Promise<ConflictResolution>);
+/** Operation tag passed to `onError` so the consumer can format its message. */
+export type AssetOp = 'loadTree' | 'loadChildren' | 'loadContent' | 'createFolder' | 'createFile' | 'uploadFile' | 'save' | 'rename' | 'delete' | 'move';
+/** Context object passed alongside `op` + `error` to `onError`. */
+export interface AssetOpContext {
+    /** Affected asset id, when known. */
+    id?: string;
+    /** Target parent id, for create/move ops. */
+    parentId?: string | null;
+    /** Asset name, for create/rename ops. */
+    name?: string;
+    /** Original file, for uploadFile. */
+    file?: File;
+}
+/**
+ * The contract a backend implements. The composable calls these and adapts
+ * the result into reactive state. Implementations should throw on failure;
+ * the composable funnels throws through `onError`.
+ *
+ * Returned `Asset<T>` objects on create/upload MUST have a stable `id`
+ * already assigned by the backend — optimistic UI uses that id to reconcile.
+ */
+export interface AssetStore<T = unknown> {
+    /**
+     * Eager: full hierarchy. Lazy: just root-level entries; mark folders with
+     * `hasChildren: true` so the tree knows they're expandable.
+     */
+    loadTree(): Promise<Asset<T>[]>;
+    /**
+     * Present → store opts into lazy loading. Called on first expand of each
+     * folder. Absent → composable runs fully eager off `loadTree()`.
+     */
+    loadChildren?(parentId: string): Promise<Asset<T>[]>;
+    /**
+     * Fetch the content of a file. Return value depends on the editor:
+     *   - `script` / `markdown` → `string`
+     *   - `pdf` / `image`       → `string` (URL) OR `Blob`
+     *
+     * Composable caches the result; subsequent opens hit cache until invalidated.
+     */
+    loadContent(id: string): Promise<string | Blob>;
+    createFolder(parentId: string | null, name: string): Promise<Asset<T>>;
+    /**
+     * Create a new empty file. The editor + language are derived from `name`
+     * via the standard fallback chain (or carried on the returned `Asset` if
+     * the backend wants explicit control).
+     */
+    createFile(parentId: string | null, name: string): Promise<Asset<T>>;
+    /**
+     * Upload an OS File (from drop or `<input type=file>`). Distinct from
+     * `createFile` so backends can pick multipart / signed-URL transports.
+     */
+    uploadFile(parentId: string | null, file: File): Promise<Asset<T>>;
+    /** Persist new file content. Composable calls this on Ctrl+S. */
+    save(id: string, content: string | Blob): Promise<void>;
+    rename(id: string, newName: string): Promise<void>;
+    delete(id: string): Promise<void>;
+    /**
+     * Move `id` under `newParentId`. `position` is the destination index
+     * inside the new parent's children. When `undefined`, append at end.
+     * `newParentId === null` means "to the root".
+     */
+    move(id: string, newParentId: string | null, position?: number): Promise<void>;
+}
+/**
+ * `createAssetStore(config)` produces an `AssetStore<T>`. The config is
+ * just a struct of the same method signatures plus framework-level concerns
+ * (`onError`, `getFileMeta`).
+ *
+ * Splitting `AssetStoreConfig` from `AssetStore` lets us add cross-cutting
+ * helpers (debouncing, retry, optimistic flags) inside `createAssetStore`
+ * without leaking them into the runtime interface every consumer of the
+ * store sees.
+ */
+export interface AssetStoreConfig<T = unknown> {
+    loadTree: AssetStore<T>['loadTree'];
+    loadChildren?: AssetStore<T>['loadChildren'];
+    loadContent: AssetStore<T>['loadContent'];
+    createFolder: AssetStore<T>['createFolder'];
+    createFile: AssetStore<T>['createFile'];
+    uploadFile: AssetStore<T>['uploadFile'];
+    save: AssetStore<T>['save'];
+    rename: AssetStore<T>['rename'];
+    delete: AssetStore<T>['delete'];
+    move: AssetStore<T>['move'];
+    /**
+     * Called whenever any store operation throws. The composable will already
+     * have rolled back the optimistic mutation by the time this fires.
+     * No return value — consumer decides what to show.
+     */
+    onError?: (op: AssetOp, error: unknown, ctx: AssetOpContext) => void;
+    /**
+     * Per-asset editor/language override. Runs AFTER `asset.editor` is
+     * checked but BEFORE the extension-based default. Use this when the
+     * editor choice depends on something other than the filename — MIME
+     * type, a backend `type` field, user preferences.
+     *
+     * Return `null` to fall through to the default heuristic.
+     */
+    getFileMeta?: (asset: Asset<T>) => FileMeta | null;
+}
+/**
+ * Comparator for two siblings, used in non-manual `sortMode`. Returns the
+ * standard `< 0 / 0 / > 0` semantics. Folders and files arrive mixed — the
+ * comparator decides any grouping (e.g. folders-first).
+ */
+export type AssetComparator<T = unknown> = (a: Asset<T>, b: Asset<T>) => number;
+/**
+ * How siblings inside a folder are ordered. Default `'folders-first'`
+ * matches VSCode's explorer; pick `'manual'` when you have a backend that
+ * can persist per-entry order (asset DB, CMS, etc.).
+ *
+ * In any non-manual mode the composable disables drop-between-siblings at
+ * the tree level — only drop-INTO-folder works.
+ */
+export type SortMode<T = unknown> = 'manual' | 'folders-first' | 'alphabetical' | AssetComparator<T>;
+/**
+ * Top-level config for `useFileExplorer(...)`. The store is the only
+ * required input — everything else is presentation polish.
+ */
+export interface FileExplorerConfig<T = unknown> {
+    store: AssetStore<T>;
+    /**
+     * Sibling ordering strategy. Default `'folders-first'` (VSCode-style).
+     * See the `SortMode` docs for the trade-offs.
+     */
+    sortMode?: SortMode<T>;
+    /** Initial selection, if any. Pass the id of a file to preselect-and-open. */
+    initialSelectionId?: string;
+    /** Folder ids that should start expanded. Default: root-level folders. */
+    initialExpandedIds?: readonly string[];
+}
+/**
+ * Imperative + reactive surface returned by `useFileExplorer`. Mirrors the
+ * shape of `useTree`'s api (loading refs first, then methods).
+ *
+ * Tabs / breadcrumb / context-menu plumbing builds on top of this — they're
+ * not part of the data plane and don't belong here.
+ */
+export interface FileExplorerApi<T = unknown> {
+    /** True while `store.loadTree()` is in flight (initial load only). */
+    readonly loading: Readonly<Ref<boolean>>;
+    /** Folder + file ids currently fetching children or content. */
+    readonly loadingNodes: Readonly<Ref<ReadonlySet<string>>>;
+    /** Ids with an in-flight save/rename/delete/move. */
+    readonly savingNodes: Readonly<Ref<ReadonlySet<string>>>;
+    /** Reactive tree, ordered. Pass directly to `<CoarTree :builder>`. */
+    readonly tree: Readonly<Ref<readonly Asset<T>[]>>;
+    /**
+     * Whether sibling reordering is honored by the configured `sortMode`.
+     * Read by the tree wiring to flip CoarTree between `'reorder'` and
+     * `'move'` draggable modes. Reactive so consumers can toggle sort modes
+     * at runtime (e.g. a "manual reorder" toggle in the toolbar).
+     */
+    readonly reorderable: Readonly<Ref<boolean>>;
+    createFolder(parentId: string | null, name: string): Promise<Asset<T>>;
+    createFile(parentId: string | null, name: string): Promise<Asset<T>>;
+    uploadFiles(parentId: string | null, files: readonly File[]): Promise<Asset<T>[]>;
+    save(id: string, content: string | Blob): Promise<void>;
+    rename(id: string, newName: string): Promise<void>;
+    delete(id: string): Promise<void>;
+    /**
+     * `position` is honored only when `sortMode === 'manual'`; otherwise it
+     * is silently dropped (the comparator decides the final position after
+     * the parent change).
+     */
+    move(id: string, newParentId: string | null, position?: number): Promise<void>;
+    /**
+     * Resolve a file's editor/language using the 3-stage fallback chain.
+     * Returns `null` for unsupported / likely-binary files (caller logs +
+     * skips, same as the POC does today).
+     */
+    fileMeta(asset: Asset<T>): FileMeta | null;
+    /** Force a re-fetch of the tree (or one folder). */
+    refresh(folderId?: string | null): Promise<void>;
+}
+/**
+ * Wraps a config into a fully-typed `AssetStore<T>`. Today this is a thin
+ * passthrough; the wrapper exists so future cross-cutting concerns
+ * (request dedup, retry, telemetry) have a home.
+ */
+export declare function createAssetStore<T = unknown>(config: AssetStoreConfig<T>): AssetStore<T>;
+/**
+ * Browser-only default implementation. Backed by a `ref<Asset<T>[]>` plus
+ * an `id → content` map. Used by the playground POC and by any consumer
+ * that wants offline / demo behaviour.
+ */
+export declare function createInMemoryAssetStore<T = unknown>(options?: {
+    /** Seed data. Optimistic ops mutate this ref in place. */
+    initialTree?: readonly Asset<T>[];
+    /** Seed file contents by id. */
+    initialContent?: Readonly<Record<string, string | Blob>>;
+    /** Artificial latency per op, for visualising loading states. Default 0. */
+    latencyMs?: number;
+    /** Random-failure rate (0..1), for exercising the error path. Default 0. */
+    failureRate?: number;
+}): AssetStore<T>;
+//# sourceMappingURL=asset-store.d.ts.map

package/dist/asset-store.d.ts.map

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

package/dist/create-asset-store.d.ts

@@ -0,0 +1,60 @@
+import { ComputedRef, MaybeRefOrGetter, Ref } from 'vue';
+import { Asset, AssetStore, AssetStoreConfig, ConflictPolicy } from './asset-store';
+export declare function createAssetStore<T = unknown>(config: AssetStoreConfig<T>): AssetStore<T>;
+export interface InMemoryAssetStoreOptions<T = unknown> {
+    /** Seed data. Mutations replace this ref's contents in place. */
+    initialTree?: readonly Asset<T>[];
+    /** Seed file contents by id. */
+    initialContent?: Readonly<Record<string, string | Blob>>;
+    /**
+     * Artificial latency per op, for visualising loading states. Default 0.
+     * Reactive: pass a `Ref<number>` / getter to retune at runtime (the
+     * playground simulator dropdown does exactly that).
+     */
+    latencyMs?: MaybeRefOrGetter<number>;
+    /**
+     * Random-failure rate (0..1), for exercising the error path. Default 0.
+     * Reactive (see `latencyMs`).
+     */
+    failureRate?: MaybeRefOrGetter<number>;
+    /**
+     * ID factory. Default: `crypto.randomUUID()`. Override for tests that
+     * need stable ids.
+     */
+    idFactory?: () => string;
+    /**
+     * What to do when a create / upload collides with an existing sibling
+     * name. Default `'rename'` (auto-suffix, macOS Finder pattern). Reactive
+     * via `Ref` / getter so the simulator can flip policies live.
+     */
+    onConflict?: MaybeRefOrGetter<ConflictPolicy<T>>;
+    /**
+     * Opt into lazy loading. When `true`:
+     *   - `loadTree()` only returns root-level entries, enriched with
+     *     `hasChildren: boolean` so the tree knows which folders are
+     *     expandable without their kids loaded.
+     *   - `loadChildren(parentId)` is exposed and returns one level deep.
+     *   - `_assets` is a computed projection over a `_publishedIds` Set —
+     *     only the published subset is visible to the composable. The full
+     *     dataset still lives in `_complete` for the store's own bookkeeping.
+     * Default: `false` (eager — composable sees everything from the start).
+     */
+    lazy?: boolean;
+}
+/**
+ * In-memory store + a peek at its raw state. Returned together so the POC
+ * (and tests) can inspect / mutate the underlying ref without going through
+ * the async API — useful for seeding, debugging, snapshotting.
+ *
+ * `_assets` is a reactive projection. In eager mode it equals the full data
+ * set; in lazy mode it equals only the published subset (root + whatever
+ * has been fetched on expand).
+ */
+export interface InMemoryAssetStore<T = unknown> extends AssetStore<T> {
+    /** Published subset (computed in lazy mode, equals everything in eager). */
+    readonly _assets: Ref<Asset<T>[]> | ComputedRef<Asset<T>[]>;
+    /** The raw content map. Mutate at your own risk. */
+    readonly _contents: Map<string, string | Blob>;
+}
+export declare function createInMemoryAssetStore<T = unknown>(options?: InMemoryAssetStoreOptions<T>): InMemoryAssetStore<T>;
+//# sourceMappingURL=create-asset-store.d.ts.map

package/dist/create-asset-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-asset-store.d.ts","sourceRoot":"","sources":["../src/create-asset-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAA0B,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,KAAK,GAAG,EAAE,MAAM,KAAK,CAAC;AAEhG,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,cAAc,EAAsB,MAAM,eAAe,CAAC;AAI7G,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAgBxF;AAID,MAAM,WAAW,yBAAyB,CAAC,CAAC,GAAG,OAAO;IACpD,iEAAiE;IACjE,WAAW,CAAC,EAAE,SAAS,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAClC,gCAAgC;IAChC,cAAc,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;IACzD;;;;OAIG;IACH,SAAS,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACrC;;;OAGG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACvC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;IACzB;;;;OAIG;IACH,UAAU,CAAC,EAAE,gBAAgB,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;IACjD;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAC;IACpE,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC5D,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CAChD;AAED,wBAAgB,wBAAwB,CAAC,CAAC,GAAG,OAAO,EAClD,OAAO,GAAE,yBAAyB,CAAC,CAAC,CAAM,GACzC,kBAAkB,CAAC,CAAC,CAAC,CAqVvB"}

package/dist/describe-asset.d.ts

@@ -0,0 +1,36 @@
+import { Asset, FileMeta } from './asset-store';
+/** One row in an asset info / details panel. */
+export interface AssetProperty {
+    /**
+     * Stable identifier for the row (`'name'`, `'type'`, `'language'`,
+     * `'extension'`, `'path'`). Lets consumers key a `v-for`, filter out rows
+     * they don't want, or splice their own rows in at a known position.
+     */
+    key: string;
+    /** Human-readable label, e.g. `'Type'`. */
+    label: string;
+    /** Human-readable value, e.g. `'Markdown'`. */
+    value: string;
+}
+/** Inputs `buildAssetProperties` needs beyond the asset itself. */
+export interface DescribeAssetContext {
+    /**
+     * Resolved editor/language for the asset, or `null` for folders and
+     * unrecognised files. `useFileExplorer().describeAsset` passes
+     * `fileMeta(asset)` for files and `null` for folders.
+     */
+    meta: FileMeta | null;
+    /**
+     * Name path from the tree root to the asset, inclusive — i.e. the result of
+     * `pathOf(asset.id)`. A single-element path (a root-level asset) omits the
+     * `'path'` row, since it would just repeat the name.
+     */
+    path: readonly string[];
+}
+/**
+ * Build the default, framework-known property rows for an asset. Folders get
+ * Name + Type (+ Path); files additionally get Language (script editor only),
+ * Extension, and Path. Returns a fresh array each call.
+ */
+export declare function buildAssetProperties<T>(asset: Asset<T>, ctx: DescribeAssetContext): AssetProperty[];
+//# sourceMappingURL=describe-asset.d.ts.map

package/dist/describe-asset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-asset.d.ts","sourceRoot":"","sources":["../src/describe-asset.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAErD,gDAAgD;AAChD,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,mEAAmE;AACnE,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IACtB;;;;OAIG;IACH,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CACzB;AAkDD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EACf,GAAG,EAAE,oBAAoB,GACxB,aAAa,EAAE,CAyBjB"}

package/dist/file-meta.d.ts

@@ -0,0 +1,21 @@
+import { Asset, AssetStoreConfig, FileMeta } from './asset-store';
+/**
+ * Map a filename to its `{ editor, language }`. Returns `null` for
+ * extensions that are recognised as binary-only (.exe, .zip, .mp4, …).
+ *
+ * The caller is expected to skip unrecognised files with a warning —
+ * matching the POC's behaviour.
+ */
+export declare function defaultFileMetaFromName(name: string): FileMeta | null;
+/**
+ * 3-stage fallback: `asset.editor` wins → then `config.getFileMeta(asset)`
+ * → then `defaultFileMetaFromName(asset.name)`. Returns `null` if all three
+ * decline (consumer override returned null + name is unrecognised).
+ *
+ * `language` is normalized to `'plaintext'` whenever the resolved editor is
+ * `'script'` but no language was supplied. Saves every consumer the
+ * `?? 'plaintext'` dance when binding to `<CoarScriptEditor :language>`;
+ * matches Monaco's own fallback for unrecognized files.
+ */
+export declare function resolveFileMeta<T>(asset: Asset<T>, config?: Pick<AssetStoreConfig<T>, 'getFileMeta'>): FileMeta | null;
+//# sourceMappingURL=file-meta.d.ts.map

package/dist/file-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-meta.d.ts","sourceRoot":"","sources":["../src/file-meta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEvE;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAyErE;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EACf,MAAM,CAAC,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,aAAa,CAAC,GAChD,QAAQ,GAAG,IAAI,CAOjB"}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `@cocoar/vue-file-explorer-core` — VSCode-style file/asset explorer composable
+ * over a pluggable `AssetStore<T>` backend.
+ *
+ * Three layers:
+ *
+ *   - **`AssetStore<T>` contract** + types — what a backend implements.
+ *     The store is the data plane: load, mutate, conflict-resolve. The
+ *     composable knows nothing about HTTP / IndexedDB / etc.
+ *   - **`createInMemoryAssetStore`** — reference implementation for
+ *     browser-only / demo use. Configurable latency, failure simulation,
+ *     lazy mode, conflict policy.
+ *   - **`useFileExplorer({store, ...})`** — the composable that wires the
+ *     store into reactive tree + tab state + async-loading bookkeeping +
+ *     keyboard-driven UX. Returns the full surface a file-explorer view
+ *     needs: refs to bind to `<CoarTree>`, ops to call on user input,
+ *     `revealInTree` / `breadcrumbPath` / `pathOf` for navigation.
+ *
+ * See the playground POC (apps/playground/src/views/FileExplorerPocView.vue)
+ * for a worked end-to-end example.
+ */
+export type { Asset, AssetComparator, AssetOp, AssetOpContext, AssetStore, AssetStoreConfig, ConflictInfo, ConflictPolicy, ConflictResolution, FileEditor, FileExplorerApi, FileExplorerConfig, FileMeta, SortMode, } from './asset-store';
+export { createAssetStore, createInMemoryAssetStore, type InMemoryAssetStore, type InMemoryAssetStoreOptions, } from './create-asset-store';
+export { defaultFileMetaFromName, resolveFileMeta, } from './file-meta';
+export { buildAssetProperties, type AssetProperty, type DescribeAssetContext, } from './describe-asset';
+export { useFileExplorer, type OpenTab, type UseFileExplorerOptions, type UseFileExplorerReturn, } from './use-file-explorer';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,YAAY,EACV,KAAK,EACL,eAAe,EACf,OAAO,EACP,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,kBAAkB,EAClB,UAAU,EACV,eAAe,EACf,kBAAkB,EAClB,QAAQ,EACR,QAAQ,GACT,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,GAC/B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,uBAAuB,EACvB,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,oBAAoB,EACpB,KAAK,aAAa,EAClB,KAAK,oBAAoB,GAC1B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,eAAe,EACf,KAAK,OAAO,EACZ,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAC"}