vfs-kit 1.0.1 → 1.0.3

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 bengru07
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 bengru07
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,35 +1,618 @@
-# vfs-kit
-A headless-first Virtual File System for React. Complete with drag-and-drop hierarchy, tab management and pluggable storage adapters.
-
-## Building the library
-
-```bash
-npm install
-npm run build
-```
-
-The package is authored in TypeScript and exports ESM modules with declaration files. React, Tailwind, and any Shadcn UI components are declared as
-peer dependencies – a consuming project must provide them.
-
-## Using locally
-
-While developing you can link the package into a demo app:
-
-```bash
-cd ./*/vfs-kit-test
-npm link vfs-kit
-```
-
-Import components in your app:
-
-```tsx
-import { TreeView, useVfs } from "vfs-kit";
-```
-
-## Notes
-
-The current release only includes a simple placeholder component. Real
-Shadcn imports can be added once you’re ready; you may need to supply a
-local `declare module '@shadcn/ui';` or update tsconfig `moduleResolution` to
-`nodenext`.
-
+# vfs-kit
+
+A headless virtual filesystem engine for React. Provides a fully typed adapter model, a caching engine, and a suite of hooks and renderless components for building file explorers, editors, and asset managers — with no opinions on styling.
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Adapters](#adapters)
+  - [InMemoryAdapter](#inmemoryadapter)
+  - [IndexedDBAdapter](#indexeddbadapter)
+  - [RestAdapter](#restadapter)
+  - [Writing a Custom Adapter](#writing-a-custom-adapter)
+- [Provider](#provider)
+- [Hooks](#hooks)
+  - [useVfs](#usevfs)
+  - [useVfsEngine](#usevfsengine)
+  - [useVfsTabs](#usevfstabs)
+  - [useVfsHistory](#usevfshistory)
+  - [useVfsExpanded](#usevfsexpanded)
+  - [useVfsSelection](#usevfsselection)
+  - [useSortableTab](#usesoratabletab)
+- [Components](#components)
+  - [FileTree](#filetree)
+  - [FileRenderer](#filerenderer)
+  - [TabList / TabListBase](#tablist--tablistbase)
+  - [InlineInput](#inlineinput)
+- [Core Types](#core-types)
+- [Roadmap](#roadmap)
+
+---
+
+## Installation
+
+```bash
+npm install vfs-kit
+```
+
+Peer dependencies: `react`, `react-dom`, `@dnd-kit/core`, `@dnd-kit/sortable`, `@dnd-kit/utilities`.
+
+For `IndexedDBAdapter`: `idb`.
+
+---
+
+## Quick Start
+
+```tsx
+import { VfsProvider } from 'vfs-kit';
+import { InMemoryAdapter } from 'vfs-kit/adapters';
+import { FileTree } from 'vfs-kit/components';
+import { useVfsEngine } from 'vfs-kit/hooks';
+
+const adapter = new InMemoryAdapter();
+
+export default function App() {
+    return (
+        <VfsProvider
+            workspaces={[{ id: 'main', name: 'My Files', adapter }]}
+            config={{ sessionId: 'user-1' }}
+        >
+            <Explorer />
+        </VfsProvider>
+    );
+}
+
+function Explorer() {
+    const { fs } = useVfsEngine('main');
+
+    return (
+        <FileTree
+            workspaceId="main"
+            renderNode={({ flatNode, onClick, dragHandleProps, style }) => (
+                <div {...dragHandleProps} onClick={onClick} style={style}>
+                    {flatNode.node.name}
+                </div>
+            )}
+        />
+    );
+}
+```
+
+---
+
+## Adapters
+
+Adapters implement the `VfsAdapter` abstract class and provide the storage backend. Three are included; you can write your own.
+
+### InMemoryAdapter
+
+Stores everything in `Map`s. No setup required. Ideal for prototyping, testing, and ephemeral state.
+
+```ts
+import { InMemoryAdapter } from 'vfs-kit/adapters';
+
+const adapter = new InMemoryAdapter();
+```
+
+Supports history (`supportsHistory = true`). Data is lost on page refresh.
+
+You can pre-seed the adapter directly before passing it to `VfsProvider`:
+
+```ts
+const root = await adapter.createFolder({ parentId: null, name: 'src' });
+const file = await adapter.createFile({ parentId: root.id, name: 'index.ts', mimeType: 'text/typescript' });
+await adapter.writeFile(file.id, new TextEncoder().encode('export {}'));
+```
+
+### IndexedDBAdapter
+
+Persists to the browser's IndexedDB via [`idb`](https://github.com/jakearchibald/idb). Survives page refresh. Supports optional cross-tab sync via `BroadcastChannel`.
+
+```ts
+import { IndexedDBAdapter } from 'vfs-kit/adapters';
+
+const adapter = new IndexedDBAdapter({
+    dbName:    'my-app-fs',
+    dbVersion: 1,              // optional, default 1
+    isolation: 'shared',       // 'private' (default) | 'shared' — enables BroadcastChannel sync
+});
+
+await adapter.open(); // must be called before passing to VfsProvider
+```
+
+Call `adapter.close()` on unmount if managing lifecycle manually.
+
+Supports history (`supportsHistory = true`). Enforces a 50-snapshot cap per file, evicting the oldest automatically.
+
+### RestAdapter
+
+Delegates all operations to a remote HTTP API. Connects to a server-sent events (SSE) endpoint for real-time change propagation, with an optional fallback for non-SSE environments.
+
+```ts
+import { RestAdapter } from 'vfs-kit/adapters';
+
+const adapter = new RestAdapter({
+    baseUrl:          'https://api.example.com/fs',
+    supportsHistory:  true,       // default true
+    fetch:            customFetch, // optional — defaults to globalThis.fetch
+    endpoints:        { ... },    // optional — override individual endpoint URLs
+    realtimeFallback: (onMessage, onError) => {
+        // e.g. set up a WebSocket and return a cleanup function
+        return () => { /* disconnect */ };
+    },
+});
+
+await adapter.open();
+```
+
+**Default endpoint conventions** (all relative to `baseUrl`):
+
+| Operation | Method | Path |
+|---|---|---|
+| Get node | GET | `/nodes/:id` |
+| Get children | GET | `/nodes/:parentId/children` |
+| Create file | POST | `/nodes/file` |
+| Create folder | POST | `/nodes/folder` |
+| Write content | PUT | `/content/:id` |
+| Move (batch) | POST | `/nodes/batch/move` |
+| Get snapshots | GET | `/snapshots/:fileId` |
+| Save snapshot | POST | `/snapshots/:fileId` |
+| Restore snapshot | POST | `/snapshots/:fileId/:index/restore` |
+| Delete snapshot | DELETE | `/snapshots/:fileId/:index` |
+| SSE stream | GET | `/events` |
+
+Any endpoint can be overridden individually via the `endpoints` option.
+
+### Writing a Custom Adapter
+
+Extend `VfsAdapter` and implement all abstract methods. Set `supportsHistory = true` and implement the four history methods (`getSnapshots`, `saveSnapshot`, `restoreSnapshot`, `deleteSnapshot`) if your backend supports it.
+
+```ts
+import { VfsAdapter } from 'vfs-kit/core';
+
+export class MyAdapter extends VfsAdapter {
+    readonly supportsHistory = false;
+    // implement abstract methods...
+}
+```
+
+---
+
+## Provider
+
+`VfsProvider` initialises the engine for each workspace and makes them available via context.
+
+```tsx
+<VfsProvider
+    workspaces={[
+        { id: 'ws-a', name: 'Source', adapter: adapterA },
+        { id: 'ws-b', name: 'Target', adapter: adapterB },
+    ]}
+    config={{
+        sessionId:           'user-123',      // required — used for node locking
+        allowDuplicateNames: false,           // default false
+        duplicateResolution: 'throw',         // 'throw' | 'rename' — default 'throw'
+        history: {
+            maxSnapshots: 50,                 // default 50
+            autosave: {
+                enabled:    false,            // default false
+                intervalMs: 30_000,
+            },
+        },
+    }}
+    cacheStrategy="hybrid"                    // 'eager' | 'lazy' | 'hybrid' — default 'hybrid'
+    tabPersistence={{ strategy: 'session' }}  // 'session' | 'none' — default 'none'
+    fallback={<div>Loading…</div>}
+>
+    {children}
+</VfsProvider>
+```
+
+**Cache strategies:**
+- `eager` — loads all nodes on init
+- `lazy` — loads nodes on demand
+- `hybrid` — loads root children on init, everything else on demand
+
+---
+
+## Hooks
+
+### useVfs
+
+The all-in-one hook. Combines engine, tabs, selection, and expanded state in a single call. Use this when you want everything wired together; use the individual hooks when you need fine-grained control.
+
+```ts
+import { useVfs } from 'vfs-kit/hooks';
+
+const {
+    fs,        // VfsFsApi   — write operations
+    tree,      // VfsTreeApi — read operations
+    status,    // VfsStatusApi
+    tabs,      // VfsTabsApi
+    selection, // VfsSelectionApi
+    expanded,  // VfsExpandedApi
+} = useVfs({
+    workspaceId: 'ws-a',           // optional — defaults to active workspace
+    tabs:      { workspaceIds: ['ws-a'] },
+    selection: { multiSelect: true, rangeSelect: true },
+    expanded:  { persistKey: 'sidebar-expanded' },
+});
+```
+
+### useVfsEngine
+
+Returns only the `fs` / `tree` / `status` surfaces for a workspace. The most commonly used hook when you don't need tabs or selection.
+
+```ts
+const { fs, tree, status } = useVfsEngine('ws-a');
+```
+
+**`fs` — write operations:**
+
+```ts
+fs.createFile(parentId, name, { mimeType?, meta? })
+fs.createFolder(parentId, name, { meta? })
+fs.rename(id, newName)
+fs.delete(ids, permanent?)        // soft-delete by default
+fs.restore(ids)
+fs.purge(ids)                     // permanent delete
+fs.move(ids, newParentId)
+fs.write(id, content)             // Uint8Array
+fs.lock(ids)
+fs.unlock(ids)
+fs.reorder(parentId, orderedIds)
+fs.snapshot(fileId, label?)
+fs.execute(command)               // raw VfsCommand escape hatch
+```
+
+**`tree` — read operations:**
+
+```ts
+tree.getNode(id)                  // Promise<VfsNode | null>
+tree.getChildren(parentId, opts?) // Promise<VfsNode[]>
+tree.getPath(id)                  // Promise<string>  e.g. '/src/index.ts'
+tree.readFile(id)                 // Promise<Uint8Array>
+tree.readJSON<T>(id)              // Promise<T>
+tree.writeJSON<T>(id, data)       // Promise<void>
+tree.search(query, opts?)
+tree.getTrashed()
+tree.getSnapshots(fileId)         // Promise<VfsFileSnapshot[]>
+```
+
+**`status`:**
+
+```ts
+status.pending  // boolean — true while a command is in flight
+status.error    // Error | null — last command error
+status.version  // number — increments on every change, useful as a cache key
+```
+
+### useVfsTabs
+
+Manages open file tabs. Supports dirty tracking, locking, drag-to-reorder, and optional session persistence.
+
+```ts
+import { useVfsTabs } from 'vfs-kit/hooks';
+
+const tabs = useVfsTabs({
+    workspaceIds: ['ws-a'],     // optional
+    dirtyChecker: ({ savedContent, currentContent }) => ..., // optional custom checker
+});
+```
+
+```ts
+tabs.tabs           // VfsTab[]
+tabs.activeTabId    // string | null
+tabs.activeTab      // VfsTab | null
+
+tabs.open(nodeId, workspaceId)   // opens or focuses a tab
+tabs.close(tabId)
+tabs.closeOthers(tabId)
+tabs.closeAll(workspaceId?)
+tabs.setActive(tabId)
+tabs.reorder(activeId, overId)
+tabs.lock(tabId)
+tabs.unlock(tabId)
+tabs.markDirty(tabId, currentContent)
+tabs.markSaved(tabId)
+```
+
+**`VfsTab` shape:**
+
+```ts
+interface VfsTab {
+    id:             string;
+    nodeId:         string;
+    workspaceId:    string;
+    title:          string;
+    isDirty:        boolean;
+    isLocked:       boolean;
+    savedContent:   Uint8Array | null;
+    currentContent: Uint8Array | null;
+    lastSavedAt:    number | null;
+}
+```
+
+> **Important:** when using a custom tab UI, use `TabListBase` and pass your `useVfsTabs` instance into it directly. Using `TabList` creates its own internal `useVfsTabs` instance which will be disconnected from yours.
+
+### useVfsHistory
+
+Per-file snapshot manager. Loads snapshots for the active file and keeps the list up to date as snapshots are taken. Scoped to the current render — history is discarded when the component unmounts.
+
+```ts
+import { useVfsHistory } from 'vfs-kit/hooks';
+
+const { snapshots, takeSnapshot, restore, remove, loading } = useVfsHistory({
+    workspaceId: 'ws-a',
+    nodeId:      'file-id',           // null clears the list
+    onRestore:   (bytes) => {         // called after a restore so you can sync editor state
+        setContent(new TextDecoder().decode(bytes));
+    },
+});
+```
+
+```ts
+takeSnapshot(label?)     // saves current file content as a new snapshot
+restore(index)           // writes snapshot content back to the file and calls onRestore
+remove(index)            // removes a snapshot
+loading                  // true while the initial snapshot list is loading
+snapshots                // VfsFileSnapshot[] — most-recent first
+```
+
+**`VfsFileSnapshot` shape:**
+
+```ts
+interface VfsFileSnapshot {
+    id:        string;
+    fileId:    string;
+    index:     number;
+    content:   Uint8Array;
+    createdAt: number;
+    label?:    string;
+}
+```
+
+Only available when the adapter has `supportsHistory = true` (`InMemoryAdapter` and `IndexedDBAdapter` both do; `RestAdapter` depends on your server).
+
+### useVfsExpanded
+
+Manages folder expanded state in a file tree. Persists to `sessionStorage` when a `persistKey` is provided. Automatically collapses deleted folders.
+
+```ts
+const expanded = useVfsExpanded({
+    workspaceIds:   ['ws-a'],            // optional
+    defaultExpanded: ['folder-id'],      // optional
+    persistKey:      'sidebar-expanded', // optional — enables sessionStorage persistence
+});
+```
+
+```ts
+expanded.expandedIds          // Set<string>
+expanded.isExpanded(id)       // boolean
+expanded.expand(id)
+expanded.collapse(id)
+expanded.toggle(id)
+expanded.expandAll(ids)
+expanded.collapseAll()
+expanded.expandToNode(id, workspaceId?)  // expands all ancestors of a node
+```
+
+### useVfsSelection
+
+Manages selected node state. Supports single select, multi-select, and shift-range select.
+
+```ts
+const selection = useVfsSelection({
+    multiSelect: true,  // default true
+    rangeSelect: true,  // default true
+});
+```
+
+```ts
+selection.selection       // string[]
+selection.lastSelectedId  // string | null
+selection.isSelected(id)  // boolean
+selection.select(id)      // replaces selection
+selection.toggle(id)      // adds/removes from selection
+selection.selectRange(orderedIds, anchorId, targetId)
+selection.deselect(id)
+selection.deselectAll()
+selection.selectAll(ids)
+```
+
+### useSortableTab
+
+A thin wrapper around `@dnd-kit/sortable`'s `useSortable` for tab drag-to-reorder. Returns `ref`, `style`, and `dragHandleProps` ready to spread onto a tab element.
+
+```ts
+import { useSortableTab } from 'vfs-kit/hooks';
+
+function MyTab({ tab }) {
+    const { ref, style, dragHandleProps } = useSortableTab(tab.id);
+    return (
+        <div ref={ref} style={style} {...dragHandleProps}>
+            {tab.title}
+        </div>
+    );
+}
+```
+
+Used internally by `TabListBase` when `sortable` is true. Use it directly when building a fully custom tab strip.
+
+---
+
+## Components
+
+All components are headless by default — they manage behaviour and delegate rendering to your own render props.
+
+### FileTree
+
+Renders a flat virtualised list of nodes for a workspace. Handles expand/collapse, drag-and-drop reordering, inline creation, and drop-zone overlays.
+
+```tsx
+import { FileTree } from 'vfs-kit/components';
+
+<FileTree
+    workspaceId="ws-a"
+    draggable                         // enables drag-and-drop
+    renderNode={({ flatNode, isSelected, isActive, isDragging, isDragSession,
+                   isRenaming, setRenaming, dragHandleProps, style, onClick }) => (
+        <div {...dragHandleProps} onClick={onClick} style={style}>
+            {flatNode.node.name}
+        </div>
+    )}
+    inlineCreate={{ kind: 'file' }}   // pass null to cancel
+    onCancelCreate={() => {}}
+    folderOverlay={{
+        mode: 'full',                 // 'full' | 'none'
+        renderOverlay: ({ isBlocked, isEmpty }) => <div />,
+    }}
+/>
+```
+
+**`NodeRenderProps`:**
+
+```ts
+interface NodeRenderProps<TMeta> {
+    flatNode:        FlatNode<TMeta>;  // { node, level, isOpen }
+    isSelected:      boolean;
+    isActive:        boolean;
+    isDragging:      boolean;
+    isDragSession:   boolean;
+    isRenaming:      boolean;
+    setRenaming:     (v: boolean) => void;
+    dragHandleProps: Record<string, unknown>;
+    style:           React.CSSProperties;
+    onClick:         (e: React.MouseEvent) => void;
+}
+```
+
+> When a file node is clicked, `FileTree`'s internal `onClick` handles selection and expand — it does not open tabs. Wire `tabs.open(node.id, workspaceId)` inside your `renderNode` click handler if you want tab behaviour.
+
+### FileRenderer
+
+Loads and renders the content of the active file. Re-runs when `activeNodeId` changes, handles loading and error states, and calls `onLoad` once content is available.
+
+```tsx
+import { FileRenderer } from 'vfs-kit/components';
+
+<FileRenderer
+    workspaceId="ws-a"
+    activeNodeId={tabs.activeTab?.nodeId ?? null}
+    onLoad={(node, bytes) => setContent(new TextDecoder().decode(bytes))}
+    onError={(node, error) => console.error(error)}
+    fallback={<div>No file open</div>}
+>
+    {({ node, content, loading, error }) => (
+        <textarea value={new TextDecoder().decode(content ?? new Uint8Array())} />
+    )}
+</FileRenderer>
+```
+
+> Key the child component on `node.id` if it owns its own content state — this causes React to fully remount on tab switch, cleanly resetting state without a `useEffect`.
+
+### TabList / TabListBase
+
+`TabList` is the higher-level component: it creates its own `useVfsTabs` instance internally.
+
+`TabListBase` is the lower-level component: it accepts tab state as props, so you can drive it from a `useVfsTabs` instance you control elsewhere. **Use `TabListBase` when you are also calling `tabs.open()` from your own code** — otherwise the tab strip and your open calls will be in two disconnected states.
+
+```tsx
+import { TabListBase } from 'vfs-kit/components';
+
+// tabs = useVfsTabs({ workspaceIds: ['ws-a'] })
+
+<TabListBase
+    tabs={tabs.tabs}
+    activeTabId={tabs.activeTabId}
+    onReorder={tabs.reorder}
+    onClose={tabs.close}
+    onSetActive={tabs.setActive}
+    onLock={tabs.lock}
+    onUnlock={tabs.unlock}
+    sortable                          // enables drag-to-reorder via @dnd-kit
+>
+    {({ tabs: tabList, activeTabId, onClose, onSetActive, onLock, onUnlock, dragHandleProps }) => (
+        <div style={{ display: 'flex' }}>
+            {tabList.map(tab => (
+                <MyTab
+                    key={tab.id}
+                    tab={tab}
+                    isActive={tab.id === activeTabId}
+                    dragHandleProps={dragHandleProps(tab.id)}
+                    onSetActive={onSetActive}
+                    onClose={onClose}
+                    onLock={onLock}
+                    onUnlock={onUnlock}
+                />
+            ))}
+        </div>
+    )}
+</TabListBase>
+```
+
+### InlineInput
+
+A controlled text input designed for inline rename flows. Commits on Enter or blur, cancels on Escape.
+
+```tsx
+import { InlineInput } from 'vfs-kit/components';
+
+<InlineInput
+    initialValue={node.name}
+    onSubmit={(newName) => fs.rename(node.id, newName)}
+    onCancel={() => setRenaming(false)}
+    className="my-input-class"
+/>
+```
+
+---
+
+## Core Types
+
+```ts
+// vfs-kit/core
+
+interface VfsNode<TMeta> {
+    id:        string;
+    name:      string;
+    kind:      'file' | 'folder';
+    parentId:  string | null;
+    sortIndex: number | null;
+    lockedBy:  string | null;
+    createdAt: number;
+    updatedAt: number;
+    deletedAt: number | null;
+    meta:      TMeta;
+}
+
+interface VfsFileNode<TMeta> extends VfsNode<TMeta> {
+    kind:     'file';
+    mimeType: string;
+    size:     number;
+}
+
+interface VfsFolderNode<TMeta> extends VfsNode<TMeta> {
+    kind: 'folder';
+}
+
+interface VfsFileSnapshot {
+    id:        string;
+    fileId:    string;
+    index:     number;
+    content:   Uint8Array;
+    createdAt: number;
+    label?:    string;
+}
+```
+
+---
+
+## Roadmap
+
+- **`deleteSnapshot` as a formal `VfsCommand`** — currently `remove()` in `useVfsHistory` is local-state only; adding `{ op: 'deleteSnapshot', fileId, index }` to `VfsEngine` and `fs.deleteSnapshot()` to `VfsFsApi` will make it durable
+- **Autosave snapshots** — `VfsEngineConfig.history.autosave` is wired in the config but not yet connected; a `setInterval` in `useVfsHistory` gated on `autosave.enabled` is the planned hookup point
+- **Snapshot diff view** — compare a snapshot's content against the current file before restoring