@bendyline/docblocks-react 0.1.0

package/src/FileExplorer/FileExplorer.tsx

@@ -0,0 +1,260 @@
+/**
+ * FileExplorer — tree component rendering FileSystemProvider contents.
+ *
+ * Shows a file/folder tree with expand/collapse, selection, and a toolbar
+ * for creating new files/folders.
+ */
+
+import { useCallback, useState } from 'react';
+import type { FileSystemProvider, FileSystemEntry } from '@bendyline/docblocks/filesystem';
+import { useFileTree } from './useFileTree.js';
+import { FileTreeNode } from './FileTreeNode.js';
+import { NewFileIcon, NewFolderIcon, RefreshIcon } from '../icons.js';
+
+const SUPPORTED_EXTENSIONS = new Set(['.txt', '.md', '.docx', '.pdf', '.dbk', '.zip']);
+
+export interface FileExplorerProps {
+  /** The filesystem to display. */
+  provider: FileSystemProvider | null;
+  /** Called when any entry is selected (file or directory). */
+  onSelect?: (path: string, kind: 'file' | 'directory') => void;
+  /** Called after any mutation (create, delete, rename). */
+  onTreeChange?: () => void;
+  /** Called when supported files are dropped onto the explorer. */
+  onImportFiles?: (files: File[]) => void;
+  /** Optional className for the root element. */
+  className?: string;
+}
+
+export function FileExplorer({
+  provider,
+  onSelect,
+  onTreeChange,
+  onImportFiles,
+  className,
+}: FileExplorerProps) {
+  const tree = useFileTree(provider);
+  const { childEntries } = tree as typeof tree & {
+    childEntries: Map<string, FileSystemEntry[]>;
+  };
+
+  const [newItemName, setNewItemName] = useState('');
+  const [newItemType, setNewItemType] = useState<'file' | 'directory' | null>(null);
+  const [dragOver, setDragOver] = useState(false);
+  const dragCounter = useState({ current: 0 })[0];
+
+  const hasSupported = useCallback((dt: DataTransfer): boolean => {
+    for (const item of Array.from(dt.items)) {
+      if (item.kind !== 'file') continue;
+      const name = (item as DataTransferItem & { getAsFile(): File | null }).getAsFile?.()?.name;
+      // During dragover the filename may not be available, so accept broadly
+      if (!name) return true;
+      const ext = name.slice(name.lastIndexOf('.')).toLowerCase();
+      if (SUPPORTED_EXTENSIONS.has(ext)) return true;
+    }
+    return dt.items.length > 0;
+  }, []);
+
+  const handleDragEnter = useCallback(
+    (e: React.DragEvent) => {
+      e.preventDefault();
+      dragCounter.current += 1;
+      if (hasSupported(e.dataTransfer)) setDragOver(true);
+    },
+    [hasSupported, dragCounter],
+  );
+
+  const handleDragOver = useCallback((e: React.DragEvent) => {
+    e.preventDefault();
+    e.dataTransfer.dropEffect = 'copy';
+  }, []);
+
+  const handleDragLeave = useCallback(
+    (e: React.DragEvent) => {
+      e.preventDefault();
+      dragCounter.current -= 1;
+      if (dragCounter.current <= 0) {
+        dragCounter.current = 0;
+        setDragOver(false);
+      }
+    },
+    [dragCounter],
+  );
+
+  const handleDrop = useCallback(
+    (e: React.DragEvent) => {
+      e.preventDefault();
+      dragCounter.current = 0;
+      setDragOver(false);
+      const supported = Array.from(e.dataTransfer.files).filter((f) => {
+        const ext = f.name.slice(f.name.lastIndexOf('.')).toLowerCase();
+        return SUPPORTED_EXTENSIONS.has(ext);
+      });
+      if (supported.length > 0) onImportFiles?.(supported);
+    },
+    [onImportFiles, dragCounter],
+  );
+
+  const handleSelect = useCallback(
+    (path: string) => {
+      // Determine kind from entries (root + children)
+      const findKind = (p: string): 'file' | 'directory' => {
+        for (const e of tree.entries) {
+          if (e.path === p) return e.kind;
+        }
+        for (const children of childEntries.values()) {
+          for (const e of children) {
+            if (e.path === p) return e.kind;
+          }
+        }
+        return 'file';
+      };
+      const kind = findKind(path);
+      tree.select(path, kind);
+      onSelect?.(path, kind);
+    },
+    [tree, onSelect, childEntries],
+  );
+
+  const handleNewItemSubmit = useCallback(async () => {
+    if (!newItemName.trim()) {
+      setNewItemType(null);
+      return;
+    }
+    const name = newItemName.trim();
+    // Scope to currently selected folder (or root)
+    const prefix =
+      tree.selectedKind === 'directory' && tree.selectedPath ? `${tree.selectedPath}/` : '';
+    if (newItemType === 'file') {
+      const filename = name.endsWith('.md') ? name : `${name}.md`;
+      await tree.createFile(`${prefix}${filename}`, '');
+    } else if (newItemType === 'directory') {
+      await tree.createDirectory(`${prefix}${name}`);
+    }
+    setNewItemName('');
+    setNewItemType(null);
+    onTreeChange?.();
+  }, [newItemName, newItemType, tree, onTreeChange]);
+
+  const handleDelete = useCallback(
+    async (path: string) => {
+      await tree.deleteEntry(path);
+      onTreeChange?.();
+    },
+    [tree, onTreeChange],
+  );
+
+  const handleRename = useCallback(
+    async (oldPath: string, newPath: string) => {
+      await tree.renameEntry(oldPath, newPath);
+      onTreeChange?.();
+    },
+    [tree, onTreeChange],
+  );
+
+  const renderEntries = useCallback(
+    (entries: FileSystemEntry[], depth: number): React.ReactNode => {
+      return entries.map((entry) => (
+        <FileTreeNode
+          key={entry.path}
+          entry={entry}
+          depth={depth}
+          expanded={tree.expanded.has(entry.path)}
+          selected={tree.selectedPath === entry.path}
+          onToggle={tree.toggleExpand}
+          onSelect={handleSelect}
+          onDelete={handleDelete}
+          onRename={handleRename}
+          renderChildren={(dirPath: string) => {
+            const children = childEntries.get(dirPath) ?? [];
+            return renderEntries(children, depth + 1);
+          }}
+        />
+      ));
+    },
+    [tree, handleSelect, handleDelete, handleRename, childEntries],
+  );
+
+  return (
+    <div
+      className={`db-file-explorer ${dragOver ? 'db-file-explorer--drop-active' : ''} ${className ?? ''}`}
+      onDragEnter={handleDragEnter}
+      onDragOver={handleDragOver}
+      onDragLeave={handleDragLeave}
+      onDrop={handleDrop}
+    >
+      {/* Toolbar */}
+      <div className="db-explorer-toolbar">
+        <span className="db-explorer-title">Files</span>
+        <div className="db-explorer-actions">
+          <button
+            className="db-explorer-btn"
+            onClick={() => setNewItemType('file')}
+            title="New File"
+            aria-label="New File"
+          >
+            <NewFileIcon />
+          </button>
+          <button
+            className="db-explorer-btn"
+            onClick={() => setNewItemType('directory')}
+            title="New Folder"
+            aria-label="New Folder"
+          >
+            <NewFolderIcon />
+          </button>
+          <button
+            className="db-explorer-btn"
+            onClick={() => tree.refresh()}
+            title="Refresh file list"
+            aria-label="Refresh file list"
+          >
+            <RefreshIcon />
+          </button>
+        </div>
+      </div>
+
+      {/* New item input */}
+      {newItemType && (
+        <div className="db-new-item">
+          <form
+            className="db-new-item-row"
+            onSubmit={(e) => {
+              e.preventDefault();
+              handleNewItemSubmit();
+            }}
+          >
+            <input
+              className="db-new-item-input"
+              placeholder={newItemType === 'file' ? 'filename' : 'folder-name'}
+              value={newItemName}
+              onChange={(e) => setNewItemName(e.target.value)}
+              onKeyDown={(e) => {
+                if (e.key === 'Escape') {
+                  setNewItemType(null);
+                  setNewItemName('');
+                }
+              }}
+              autoFocus
+            />
+            {newItemType === 'file' && <span className="db-new-item-suffix">.md</span>}
+            <button type="submit" className="db-new-item-add">
+              Add
+            </button>
+          </form>
+        </div>
+      )}
+
+      {/* Tree */}
+      <div className="db-tree" role="tree">
+        {tree.loading ? (
+          <div className="db-tree-loading">Loading...</div>
+        ) : tree.entries.length === 0 ? (
+          <div className="db-tree-empty">No files yet</div>
+        ) : (
+          renderEntries(tree.entries, 0)
+        )}
+      </div>
+    </div>
+  );
+}

package/src/FileExplorer/FileTreeNode.tsx

@@ -0,0 +1,172 @@
+/**
+ * FileTreeNode — recursive tree node for the file explorer.
+ */
+
+import { useCallback, useState, useRef, useEffect } from 'react';
+import type { FileSystemEntry } from '@bendyline/docblocks/filesystem';
+
+export interface FileTreeNodeProps {
+  entry: FileSystemEntry;
+  depth: number;
+  expanded: boolean;
+  selected: boolean;
+  children?: FileSystemEntry[];
+  onToggle: (path: string) => void;
+  onSelect: (path: string) => void;
+  onDelete: (path: string) => Promise<void>;
+  onRename: (oldPath: string, newPath: string) => Promise<void>;
+  renderChildren?: (dirPath: string) => React.ReactNode;
+}
+
+export function FileTreeNode({
+  entry,
+  depth,
+  expanded,
+  selected,
+  onToggle,
+  onSelect,
+  onDelete,
+  onRename,
+  renderChildren,
+}: FileTreeNodeProps) {
+  const [renaming, setRenaming] = useState(false);
+  const [renameValue, setRenameValue] = useState(entry.name);
+  const [showContext, setShowContext] = useState(false);
+  const [contextPos, setContextPos] = useState({ x: 0, y: 0 });
+  const inputRef = useRef<HTMLInputElement>(null);
+  const contextRef = useRef<HTMLDivElement>(null);
+  const nodeRef = useRef<HTMLDivElement>(null);
+
+  const isDir = entry.kind === 'directory';
+  const icon = isDir ? (expanded ? '\u25BE' : '\u25B8') : '\u00A0\u00A0';
+
+  const handleClick = useCallback(() => {
+    if (isDir) {
+      onToggle(entry.path);
+    }
+    onSelect(entry.path);
+  }, [isDir, entry.path, onToggle, onSelect]);
+
+  const handleContextMenu = useCallback((e: React.MouseEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+    const rect = nodeRef.current?.getBoundingClientRect();
+    setContextPos({
+      x: e.clientX - (rect?.left ?? 0),
+      y: e.clientY - (rect?.top ?? 0),
+    });
+    setShowContext(true);
+  }, []);
+
+  const handleRenameStart = useCallback(() => {
+    setRenameValue(entry.name);
+    setRenaming(true);
+    setShowContext(false);
+  }, [entry.name]);
+
+  const handleRenameSubmit = useCallback(async () => {
+    if (renameValue && renameValue !== entry.name) {
+      const parentPath = entry.path.includes('/')
+        ? entry.path.slice(0, entry.path.lastIndexOf('/'))
+        : '';
+      const newPath = parentPath ? `${parentPath}/${renameValue}` : renameValue;
+      await onRename(entry.path, newPath);
+    }
+    setRenaming(false);
+  }, [renameValue, entry.name, entry.path, onRename]);
+
+  const handleDeleteClick = useCallback(async () => {
+    setShowContext(false);
+    await onDelete(entry.path);
+  }, [entry.path, onDelete]);
+
+  // Close context menu on outside click or scroll
+  useEffect(() => {
+    if (!showContext) return;
+    function handleClose(e: Event) {
+      if (contextRef.current && !contextRef.current.contains(e.target as Node)) {
+        setShowContext(false);
+      }
+    }
+    // Use click (not mousedown) so menu button clicks register first
+    document.addEventListener('click', handleClose, true);
+    document.addEventListener('contextmenu', handleClose, true);
+    document.addEventListener('scroll', () => setShowContext(false), { capture: true, once: true });
+    return () => {
+      document.removeEventListener('click', handleClose, true);
+      document.removeEventListener('contextmenu', handleClose, true);
+    };
+  }, [showContext]);
+
+  // Focus input when renaming
+  useEffect(() => {
+    if (renaming && inputRef.current) {
+      inputRef.current.focus();
+      inputRef.current.select();
+    }
+  }, [renaming]);
+
+  return (
+    <div className="db-tree-node" ref={nodeRef}>
+      <div
+        className={`db-tree-row ${selected ? 'db-tree-row--selected' : ''}`}
+        style={{ paddingLeft: depth * 16 + 4 }}
+        onClick={handleClick}
+        onContextMenu={handleContextMenu}
+        role="treeitem"
+        aria-expanded={isDir ? expanded : undefined}
+        aria-selected={selected}
+        tabIndex={0}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter') handleClick();
+        }}
+      >
+        <span className="db-tree-icon">{icon}</span>
+        {renaming ? (
+          <input
+            ref={inputRef}
+            className="db-tree-rename-input"
+            value={renameValue}
+            onChange={(e) => setRenameValue(e.target.value)}
+            onBlur={handleRenameSubmit}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter') handleRenameSubmit();
+              if (e.key === 'Escape') setRenaming(false);
+            }}
+            onClick={(e) => e.stopPropagation()}
+          />
+        ) : (
+          <span className="db-tree-label">
+            {entry.name.endsWith('.md') ? entry.name.slice(0, -3) : entry.name}
+          </span>
+        )}
+      </div>
+
+      {/* Context menu */}
+      {showContext && (
+        <div
+          ref={contextRef}
+          className="db-tree-context"
+          style={{ left: contextPos.x, top: contextPos.y }}
+        >
+          <button className="db-tree-context-item" onClick={handleRenameStart}>
+            Rename
+          </button>
+          <button
+            className="db-tree-context-item db-tree-context-item--danger"
+            onClick={handleDeleteClick}
+          >
+            Delete
+          </button>
+        </div>
+      )}
+
+      {/* Render children if directory is expanded */}
+      {isDir && expanded && renderChildren && (
+        <div className="db-tree-children" role="group">
+          {renderChildren(entry.path)}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/FileExplorer/index.ts

@@ -0,0 +1,5 @@
+export { FileExplorer } from './FileExplorer.js';
+export type { FileExplorerProps } from './FileExplorer.js';
+export { FileTreeNode } from './FileTreeNode.js';
+export type { FileTreeNodeProps } from './FileTreeNode.js';
+export { useFileTree } from './useFileTree.js';

package/src/FileExplorer/useFileTree.ts

@@ -0,0 +1,178 @@
+/**
+ * useFileTree — hook that reads from a FileSystemProvider,
+ * maintains expanded/collapsed state, and provides CRUD operations.
+ */
+
+import { useState, useCallback, useEffect, useRef } from 'react';
+import type { FileSystemProvider, FileSystemEntry } from '@bendyline/docblocks/filesystem';
+
+export interface FileTreeState {
+  /** Flat list of entries for the current directory view. */
+  entries: FileSystemEntry[];
+  /** Set of expanded directory paths. */
+  expanded: Set<string>;
+  /** Currently selected path — file or directory (null if none). */
+  selectedPath: string | null;
+  /** Kind of the selected entry. */
+  selectedKind: 'file' | 'directory' | null;
+  /** Whether the tree is loading. */
+  loading: boolean;
+}
+
+export interface FileTreeActions {
+  /** Toggle a directory's expanded state. */
+  toggleExpand: (path: string) => void;
+  /** Select a file or directory. */
+  select: (path: string, kind: 'file' | 'directory') => void;
+  /** Create a new file with optional initial content. */
+  createFile: (path: string, content?: string) => Promise<void>;
+  /** Create a new directory. */
+  createDirectory: (path: string) => Promise<void>;
+  /** Delete a file or directory. */
+  deleteEntry: (path: string) => Promise<void>;
+  /** Rename a file or directory. */
+  renameEntry: (oldPath: string, newPath: string) => Promise<void>;
+  /** Force refresh the tree. */
+  refresh: () => Promise<void>;
+}
+
+export function useFileTree(provider: FileSystemProvider | null): FileTreeState & FileTreeActions {
+  const [entries, setEntries] = useState<FileSystemEntry[]>([]);
+  const [expanded, setExpanded] = useState<Set<string>>(new Set());
+  const [selectedPath, setSelectedPath] = useState<string | null>(null);
+  const [selectedKind, setSelectedKind] = useState<'file' | 'directory' | null>(null);
+  const [loading, setLoading] = useState(false);
+
+  // Track child entries for expanded directories
+  const [childEntries, setChildEntries] = useState<Map<string, FileSystemEntry[]>>(new Map());
+
+  const providerRef = useRef(provider);
+  providerRef.current = provider;
+
+  const loadRoot = useCallback(async () => {
+    if (!providerRef.current) {
+      setEntries([]);
+      return;
+    }
+    setLoading(true);
+    try {
+      const root = await providerRef.current.readDirectory('');
+      setEntries(root);
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  const loadChildren = useCallback(async (dirPath: string) => {
+    if (!providerRef.current) return;
+    const children = await providerRef.current.readDirectory(dirPath);
+    setChildEntries((prev) => {
+      const next = new Map(prev);
+      next.set(dirPath, children);
+      return next;
+    });
+  }, []);
+
+  // Load root on provider change
+  useEffect(() => {
+    setExpanded(new Set());
+    setChildEntries(new Map());
+    setSelectedPath(null);
+    setSelectedKind(null);
+    loadRoot();
+  }, [provider, loadRoot]);
+
+  const toggleExpand = useCallback(
+    (path: string) => {
+      setExpanded((prev) => {
+        const next = new Set(prev);
+        if (next.has(path)) {
+          next.delete(path);
+        } else {
+          next.add(path);
+          // Load children when expanding
+          loadChildren(path);
+        }
+        return next;
+      });
+    },
+    [loadChildren],
+  );
+
+  const select = useCallback((path: string, kind: 'file' | 'directory') => {
+    setSelectedPath(path);
+    setSelectedKind(kind);
+  }, []);
+
+  const refresh = useCallback(async () => {
+    await loadRoot();
+    // Reload all expanded directories
+    const expandedPaths = [...expanded];
+    for (const dirPath of expandedPaths) {
+      await loadChildren(dirPath);
+    }
+  }, [loadRoot, loadChildren, expanded]);
+
+  const createFile = useCallback(
+    async (path: string, content = '') => {
+      if (!providerRef.current) return;
+      await providerRef.current.writeFile(path, content);
+      await refresh();
+    },
+    [refresh],
+  );
+
+  const createDirectory = useCallback(
+    async (path: string) => {
+      if (!providerRef.current) return;
+      await providerRef.current.createDirectory(path);
+      await refresh();
+    },
+    [refresh],
+  );
+
+  const deleteEntry = useCallback(
+    async (path: string) => {
+      if (!providerRef.current) return;
+      await providerRef.current.delete(path);
+      if (selectedPath === path) {
+        setSelectedPath(null);
+        setSelectedKind(null);
+      }
+      await refresh();
+    },
+    [refresh, selectedPath],
+  );
+
+  const renameEntry = useCallback(
+    async (oldPath: string, newPath: string) => {
+      if (!providerRef.current) return;
+      await providerRef.current.rename(oldPath, newPath);
+      if (selectedPath === oldPath) {
+        setSelectedPath(newPath);
+      }
+      await refresh();
+    },
+    [refresh, selectedPath],
+  );
+
+  // Merge root entries with child entries for a flat tree representation
+  // (consumers use `expanded` and `childEntries` to render recursively)
+
+  return {
+    entries,
+    expanded,
+    selectedPath,
+    selectedKind,
+    loading,
+    toggleExpand,
+    select,
+    createFile,
+    createDirectory,
+    deleteEntry,
+    renameEntry,
+    refresh,
+    // Expose child entries for rendering
+    ...{ childEntries },
+  } as FileTreeState & FileTreeActions & { childEntries: Map<string, FileSystemEntry[]> };
+}