@bendyline/docblocks-react 1.1.2 → 2.1.0

package/src/FileExplorer/FileExplorer.tsx

@@ -1,282 +0,0 @@
-/**
- * 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']);
-
-/**
- * Hide auto-generated `<basename>_files/` companion folders from the
- * tree. They hold per-document images and version snapshots — useful
- * to the editor, noisy in the user-facing file list. The folders still
- * exist on disk; we just don't surface them in the explorer.
- */
-function isHiddenEntry(entry: FileSystemEntry): boolean {
-  if (entry.kind !== 'directory') return false;
-  const name = entry.path.replace(/^\/+/, '').split('/').pop() ?? '';
-  return name.endsWith('_files');
-}
-
-function filterVisible(entries: FileSystemEntry[]): FileSystemEntry[] {
-  return entries.filter((e) => !isHiddenEntry(e));
-}
-
-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 filterVisible(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 — role="tree" only when there are real treeitem children; the
-          loading/empty states get a status role so axe doesn't flag the
-          tree as missing required children. */}
-      {tree.loading ? (
-        <div className="db-tree" role="status" aria-live="polite">
-          <div className="db-tree-loading">Loading...</div>
-        </div>
-      ) : filterVisible(tree.entries).length === 0 ? (
-        <div className="db-tree">
-          <div className="db-tree-empty">No files yet</div>
-        </div>
-      ) : (
-        <div className="db-tree" role="tree">
-          {renderEntries(tree.entries, 0)}
-        </div>
-      )}
-    </div>
-  );
-}

package/src/FileExplorer/FileTreeNode.tsx

@@ -1,214 +0,0 @@
-/**
- * FileTreeNode — recursive tree node for the file explorer.
- */
-
-import { useCallback, useState, useRef, useEffect, useLayoutEffect } from 'react';
-import { createPortal } from 'react-dom';
-import type { FileSystemEntry } from '@bendyline/docblocks/filesystem';
-import { MoreIcon } from '../icons.js';
-
-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();
-    setContextPos({ x: e.clientX, y: e.clientY });
-    setShowContext(true);
-  }, []);
-
-  const handleMoreClick = useCallback((e: React.MouseEvent) => {
-    e.preventDefault();
-    e.stopPropagation();
-    const rect = (e.currentTarget as HTMLElement).getBoundingClientRect();
-    setContextPos({ x: rect.right, y: rect.bottom });
-    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]);
-
-  // Clamp menu inside viewport after it renders
-  useLayoutEffect(() => {
-    if (!showContext || !contextRef.current) return;
-    const menu = contextRef.current;
-    const rect = menu.getBoundingClientRect();
-    const margin = 4;
-    let left = contextPos.x;
-    let top = contextPos.y;
-    if (rect.right > window.innerWidth - margin) {
-      left = Math.max(margin, window.innerWidth - rect.width - margin);
-    }
-    if (rect.bottom > window.innerHeight - margin) {
-      top = Math.max(margin, window.innerHeight - rect.height - margin);
-    }
-    if (left !== contextPos.x || top !== contextPos.y) {
-      menu.style.left = `${left}px`;
-      menu.style.top = `${top}px`;
-    }
-  }, [showContext, contextPos]);
-
-  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>
-            <button
-              type="button"
-              className={`db-tree-more${showContext ? ' db-tree-more--active' : ''}`}
-              onClick={handleMoreClick}
-              onContextMenu={handleMoreClick}
-              aria-label="More actions"
-              aria-haspopup="menu"
-              aria-expanded={showContext}
-              tabIndex={-1}
-            >
-              <MoreIcon width={14} height={14} />
-            </button>
-          </>
-        )}
-      </div>
-
-      {/* Context menu — portaled so ancestor overflow:hidden doesn't clip it */}
-      {showContext &&
-        createPortal(
-          <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>,
-          document.body,
-        )}
-
-      {/* 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

@@ -1,5 +0,0 @@
-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

@@ -1,178 +0,0 @@
-/**
- * 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[]> };
-}