@bendyline/docblocks-react 2.0.0 → 2.1.1

package/src/FileExplorer/FileTreeNode.tsx

@@ -1,306 +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';
-
-/** Git decoration for a row — precomputed by FileExplorer so this node stays context-free. */
-export interface FileTreeNodeBadge {
-  kind: string;
-  glyph: string;
-  label: string;
-}
-
-/** Git context-menu actions, prebound to this entry's path. */
-export interface FileTreeNodeGitActions {
-  viewChanges?: () => void;
-  fileHistory?: () => void;
-  openOnRemote?: () => void;
-}
-
-export interface FileTreeNodeProps {
-  entry: FileSystemEntry;
-  depth: number;
-  expanded: boolean;
-  selected: boolean;
-  badge?: FileTreeNodeBadge;
-  gitActions?: FileTreeNodeGitActions;
-  children?: FileSystemEntry[];
-  onToggle: (path: string) => void;
-  onSelect: (path: string) => void;
-  onDelete: (path: string, kind: 'file' | 'directory') => Promise<void>;
-  onRename: (oldPath: string, newPath: string, kind: 'file' | 'directory') => Promise<void>;
-  draggable?: boolean;
-  dragging?: boolean;
-  dropTarget?: boolean;
-  onDragStart?: (event: React.DragEvent, entry: FileSystemEntry) => void;
-  onDragEnd?: () => void;
-  onDragOverEntry?: (event: React.DragEvent, entry: FileSystemEntry) => void;
-  onDropEntry?: (event: React.DragEvent, entry: FileSystemEntry) => void;
-  renderChildren?: (dirPath: string) => React.ReactNode;
-}
-
-export function FileTreeNode({
-  entry,
-  depth,
-  expanded,
-  selected,
-  badge,
-  gitActions,
-  onToggle,
-  onSelect,
-  onDelete,
-  onRename,
-  draggable = false,
-  dragging = false,
-  dropTarget = false,
-  onDragStart,
-  onDragEnd,
-  onDragOverEntry,
-  onDropEntry,
-  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, entry.kind);
-    }
-    setRenaming(false);
-  }, [renameValue, entry.name, entry.path, entry.kind, onRename]);
-
-  const handleDeleteClick = useCallback(async () => {
-    setShowContext(false);
-    const description = entry.kind === 'directory' ? 'folder and everything inside it' : 'document';
-    if (!window.confirm(`Delete the ${description} "${entry.name}"? This cannot be undone.`)) {
-      return;
-    }
-    await onDelete(entry.path, entry.kind);
-  }, [entry.name, entry.path, entry.kind, 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]);
-
-  // Active documents can be revealed after asynchronous ancestor loads. Keep
-  // the selected row inside the explorer's scroll viewport once it mounts.
-  useEffect(() => {
-    if (selected) nodeRef.current?.scrollIntoView?.({ block: 'nearest' });
-  }, [selected]);
-
-  // 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' : ''} ${dragging ? 'db-tree-row--dragging' : ''} ${dropTarget ? 'db-tree-row--drop-target' : ''}`}
-        style={{ paddingLeft: depth * 16 + 4 }}
-        onClick={handleClick}
-        onContextMenu={handleContextMenu}
-        draggable={draggable && !renaming}
-        onDragStart={(event) => onDragStart?.(event, entry)}
-        onDragEnd={onDragEnd}
-        onDragOver={(event) => onDragOverEntry?.(event, entry)}
-        onDrop={(event) => onDropEntry?.(event, entry)}
-        role="treeitem"
-        aria-expanded={isDir ? expanded : undefined}
-        aria-selected={selected}
-        aria-label={badge ? `${entry.name}, ${badge.label}` : undefined}
-        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>
-            {badge && (
-              <span className={`db-git-badge db-git-badge--${badge.kind}`} aria-hidden="true">
-                {badge.glyph}
-              </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 />
-            </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>
-            {gitActions && (gitActions.viewChanges || gitActions.fileHistory) && (
-              <>
-                <div className="db-tree-context-divider" role="separator" />
-                {gitActions.viewChanges && (
-                  <button
-                    className="db-tree-context-item"
-                    onClick={() => {
-                      setShowContext(false);
-                      gitActions.viewChanges?.();
-                    }}
-                  >
-                    View changes
-                  </button>
-                )}
-                {gitActions.fileHistory && (
-                  <button
-                    className="db-tree-context-item"
-                    onClick={() => {
-                      setShowContext(false);
-                      gitActions.fileHistory?.();
-                    }}
-                  >
-                    File history…
-                  </button>
-                )}
-                {gitActions.openOnRemote && (
-                  <button
-                    className="db-tree-context-item"
-                    onClick={() => {
-                      setShowContext(false);
-                      gitActions.openOnRemote?.();
-                    }}
-                  >
-                    Open on remote
-                  </button>
-                )}
-                <div className="db-tree-context-divider" role="separator" />
-              </>
-            )}
-            <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, FileTreeChange, FileTreeMutationHandler } 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,352 +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 {
-  getFileSystemProviderV2,
-  moveFileSystemEntry,
-  parseWorkspacePath,
-  type FileSystemProvider,
-  type FileSystemEntry,
-} from '@bendyline/docblocks/filesystem';
-
-function normalisePath(path: string): string {
-  return parseWorkspacePath(path);
-}
-
-function relocatePath(path: string, oldPath: string, newPath: string): string {
-  const current = normalisePath(path);
-  const oldNormalised = normalisePath(oldPath);
-  if (current !== oldNormalised && !current.startsWith(`${oldNormalised}/`)) return path;
-  const suffix = current.slice(oldNormalised.length);
-  return `${newPath.replace(/\/+$/, '')}${suffix}`;
-}
-
-function ancestorPaths(path: string): string[] {
-  const canonical = normalisePath(path);
-  if (!canonical) return [];
-  const segments = canonical.split('/');
-  const prefix = /^[\\/]/u.test(path) ? '/' : '';
-  return segments
-    .slice(0, -1)
-    .map((_, index) => `${prefix}${segments.slice(0, index + 1).join('/')}`);
-}
-
-function equivalentPathKeys(path: string): string[] {
-  const canonical = normalisePath(path);
-  return canonical ? [path, canonical, `/${canonical}`] : [path, canonical];
-}
-
-function hasEquivalentPath(paths: ReadonlySet<string>, path: string): boolean {
-  return equivalentPathKeys(path).some((candidate) => paths.has(candidate));
-}
-
-async function readProviderDirectory(
-  provider: FileSystemProvider,
-  path: string,
-): Promise<FileSystemEntry[]> {
-  const providerV2 = getFileSystemProviderV2(provider);
-  if (!providerV2) return provider.readDirectory(path);
-  const entries = await providerV2.readDirectory(parseWorkspacePath(path));
-  return entries.map((entry) => ({ kind: entry.kind, name: entry.name, path: entry.path }));
-}
-
-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;
-  /** Select an entry and expand each directory needed to reveal it. */
-  reveal: (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 or move a file or directory, including a markdown companion folder. */
-  renameEntry: (oldPath: string, newPath: string, kind?: 'file' | 'directory') => 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 readProviderDirectory(providerRef.current, '');
-      setEntries(root);
-    } finally {
-      setLoading(false);
-    }
-  }, []);
-
-  const loadChildren = useCallback(async (dirPath: string) => {
-    if (!providerRef.current) return;
-    const children = await readProviderDirectory(providerRef.current, 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 (hasEquivalentPath(next, path)) {
-          for (const candidate of equivalentPathKeys(path)) next.delete(candidate);
-        } 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 reveal = useCallback(
-    (path: string, kind: 'file' | 'directory') => {
-      const ancestors = ancestorPaths(path);
-      setSelectedPath(path);
-      setSelectedKind(kind);
-      setExpanded((prev) => {
-        const next = new Set(prev);
-        for (const ancestor of ancestors) {
-          if (!hasEquivalentPath(next, ancestor)) next.add(ancestor);
-        }
-        return next;
-      });
-      for (const ancestor of ancestors) {
-        void loadChildren(ancestor);
-      }
-    },
-    [loadChildren],
-  );
-
-  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 refreshRef = useRef(refresh);
-  refreshRef.current = refresh;
-
-  // Keep the explorer synchronized with provider changes. Watch-capable
-  // providers (including Electron's chokidar-backed provider) update in real
-  // time. Calls are serialized and coalesced so event bursts cannot publish
-  // directory reads out of order.
-  useEffect(() => {
-    if (!provider) return;
-    const providerV2 = getFileSystemProviderV2(provider);
-    if (!providerV2?.capabilities.watch) return;
-
-    let disposed = false;
-    let refreshing = false;
-    let refreshAgain = false;
-
-    const requestRefresh = () => {
-      if (disposed) return;
-      if (refreshing) {
-        refreshAgain = true;
-        return;
-      }
-      refreshing = true;
-      void (async () => {
-        try {
-          do {
-            refreshAgain = false;
-            await refreshRef.current();
-          } while (refreshAgain && !disposed);
-        } catch {
-          // A later watcher event or window resume will retry the read.
-        } finally {
-          refreshing = false;
-          if (refreshAgain && !disposed) requestRefresh();
-        }
-      })();
-    };
-
-    const subscription = providerV2.watch(requestRefresh, { onError: requestRefresh });
-    void subscription.ready.catch(() => undefined);
-    return () => {
-      disposed = true;
-      void subscription.dispose();
-    };
-  }, [provider]);
-
-  // File System Access and IndexedDB do not expose a dependable external
-  // watcher. Refreshing on resume catches changes made while this surface was
-  // in the background without continuously polling the filesystem.
-  useEffect(() => {
-    if (!provider) return;
-    const refreshOnFocus = () => {
-      void refreshRef.current().catch(() => undefined);
-    };
-    const refreshOnVisibility = () => {
-      if (document.visibilityState === 'visible') refreshOnFocus();
-    };
-    window.addEventListener('focus', refreshOnFocus);
-    document.addEventListener('visibilitychange', refreshOnVisibility);
-    return () => {
-      window.removeEventListener('focus', refreshOnFocus);
-      document.removeEventListener('visibilitychange', refreshOnVisibility);
-    };
-  }, [provider]);
-
-  const createFile = useCallback(
-    async (path: string, content = '') => {
-      if (!providerRef.current) return;
-      const providerV2 = getFileSystemProviderV2(providerRef.current);
-      if (providerV2) {
-        await providerV2.writeFile(parseWorkspacePath(path), new TextEncoder().encode(content), {
-          mode: 'create',
-        });
-      } else {
-        await providerRef.current.writeFile(path, content);
-      }
-      await refresh();
-    },
-    [refresh],
-  );
-
-  const createDirectory = useCallback(
-    async (path: string) => {
-      if (!providerRef.current) return;
-      const providerV2 = getFileSystemProviderV2(providerRef.current);
-      if (providerV2) {
-        await providerV2.createDirectory(parseWorkspacePath(path), { mode: 'create' });
-      } else {
-        await providerRef.current.createDirectory(path);
-      }
-      await refresh();
-    },
-    [refresh],
-  );
-
-  const deleteEntry = useCallback(
-    async (path: string) => {
-      if (!providerRef.current) return;
-      const providerV2 = getFileSystemProviderV2(providerRef.current);
-      if (providerV2) {
-        const canonical = parseWorkspacePath(path);
-        const entry = await providerV2.stat(canonical);
-        if (entry) {
-          await providerV2.remove(canonical, {
-            recursive: entry.kind === 'directory',
-            missing: 'error',
-            expectedVersion: entry.version,
-          });
-        }
-      } else {
-        await providerRef.current.delete(path);
-      }
-      if (selectedPath === path) {
-        setSelectedPath(null);
-        setSelectedKind(null);
-      }
-      await refresh();
-    },
-    [refresh, selectedPath],
-  );
-
-  const renameEntry = useCallback(
-    async (oldPath: string, newPath: string, kind?: 'file' | 'directory') => {
-      if (!providerRef.current) return;
-      const oldNormalised = normalisePath(oldPath);
-      const knownEntry = [...entries, ...childEntries.values()]
-        .flat()
-        .find((entry) => normalisePath(entry.path) === oldNormalised);
-      const entryKind = kind ?? knownEntry?.kind ?? 'file';
-      await moveFileSystemEntry(providerRef.current, oldPath, newPath, entryKind);
-
-      if (selectedPath) {
-        setSelectedPath(relocatePath(selectedPath, oldPath, newPath));
-      }
-
-      const nextExpanded = new Set(
-        [...expanded].map((path) => relocatePath(path, oldPath, newPath)),
-      );
-      setExpanded(nextExpanded);
-      setChildEntries(new Map());
-      await loadRoot();
-      for (const dirPath of nextExpanded) {
-        await loadChildren(dirPath);
-      }
-    },
-    [selectedPath, entries, childEntries, expanded, loadRoot, loadChildren],
-  );
-
-  // 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,
-    reveal,
-    createFile,
-    createDirectory,
-    deleteEntry,
-    renameEntry,
-    refresh,
-    // Expose child entries for rendering
-    ...{ childEntries },
-  } as FileTreeState & FileTreeActions & { childEntries: Map<string, FileSystemEntry[]> };
-}