@bendyline/docblocks-react 1.1.2 → 2.0.0

package/src/FileExplorer/FileTreeNode.tsx

@@ -7,16 +7,39 @@ 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) => Promise<void>;
-  onRename: (oldPath: string, newPath: string) => Promise<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;
 }
 
@@ -25,10 +48,19 @@ export function FileTreeNode({
   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);
@@ -76,15 +108,19 @@ export function FileTreeNode({
         ? entry.path.slice(0, entry.path.lastIndexOf('/'))
         : '';
       const newPath = parentPath ? `${parentPath}/${renameValue}` : renameValue;
-      await onRename(entry.path, newPath);
+      await onRename(entry.path, newPath, entry.kind);
     }
     setRenaming(false);
-  }, [renameValue, entry.name, entry.path, onRename]);
+  }, [renameValue, entry.name, entry.path, entry.kind, onRename]);
 
   const handleDeleteClick = useCallback(async () => {
     setShowContext(false);
-    await onDelete(entry.path);
-  }, [entry.path, onDelete]);
+    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(() => {
@@ -112,6 +148,12 @@ export function FileTreeNode({
     }
   }, [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;
@@ -135,13 +177,19 @@ export function FileTreeNode({
   return (
     <div className="db-tree-node" ref={nodeRef}>
       <div
-        className={`db-tree-row ${selected ? 'db-tree-row--selected' : ''}`}
+        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();
@@ -166,6 +214,11 @@ export function FileTreeNode({
             <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' : ''}`}
@@ -176,7 +229,7 @@ export function FileTreeNode({
               aria-expanded={showContext}
               tabIndex={-1}
             >
-              <MoreIcon width={14} height={14} />
+              <MoreIcon />
             </button>
           </>
         )}
@@ -193,6 +246,45 @@ export function FileTreeNode({
             <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}

package/src/FileExplorer/index.ts

@@ -1,5 +1,5 @@
 export { FileExplorer } from './FileExplorer.js';
-export type { FileExplorerProps } 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

@@ -4,7 +4,54 @@
  */
 
 import { useState, useCallback, useEffect, useRef } from 'react';
-import type { FileSystemProvider, FileSystemEntry } from '@bendyline/docblocks/filesystem';
+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. */
@@ -24,14 +71,16 @@ export interface FileTreeActions {
   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 a file or directory. */
-  renameEntry: (oldPath: string, newPath: 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>;
 }
@@ -56,7 +105,7 @@ export function useFileTree(provider: FileSystemProvider | null): FileTreeState
     }
     setLoading(true);
     try {
-      const root = await providerRef.current.readDirectory('');
+      const root = await readProviderDirectory(providerRef.current, '');
       setEntries(root);
     } finally {
       setLoading(false);
@@ -65,7 +114,7 @@ export function useFileTree(provider: FileSystemProvider | null): FileTreeState
 
   const loadChildren = useCallback(async (dirPath: string) => {
     if (!providerRef.current) return;
-    const children = await providerRef.current.readDirectory(dirPath);
+    const children = await readProviderDirectory(providerRef.current, dirPath);
     setChildEntries((prev) => {
       const next = new Map(prev);
       next.set(dirPath, children);
@@ -86,8 +135,8 @@ export function useFileTree(provider: FileSystemProvider | null): FileTreeState
     (path: string) => {
       setExpanded((prev) => {
         const next = new Set(prev);
-        if (next.has(path)) {
-          next.delete(path);
+        if (hasEquivalentPath(next, path)) {
+          for (const candidate of equivalentPathKeys(path)) next.delete(candidate);
         } else {
           next.add(path);
           // Load children when expanding
@@ -104,6 +153,25 @@ export function useFileTree(provider: FileSystemProvider | null): FileTreeState
     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
@@ -113,10 +181,82 @@ export function useFileTree(provider: FileSystemProvider | null): FileTreeState
     }
   }, [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;
-      await providerRef.current.writeFile(path, content);
+      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],
@@ -125,7 +265,12 @@ export function useFileTree(provider: FileSystemProvider | null): FileTreeState
   const createDirectory = useCallback(
     async (path: string) => {
       if (!providerRef.current) return;
-      await providerRef.current.createDirectory(path);
+      const providerV2 = getFileSystemProviderV2(providerRef.current);
+      if (providerV2) {
+        await providerV2.createDirectory(parseWorkspacePath(path), { mode: 'create' });
+      } else {
+        await providerRef.current.createDirectory(path);
+      }
       await refresh();
     },
     [refresh],
@@ -134,7 +279,20 @@ export function useFileTree(provider: FileSystemProvider | null): FileTreeState
   const deleteEntry = useCallback(
     async (path: string) => {
       if (!providerRef.current) return;
-      await providerRef.current.delete(path);
+      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);
@@ -145,15 +303,30 @@ export function useFileTree(provider: FileSystemProvider | null): FileTreeState
   );
 
   const renameEntry = useCallback(
-    async (oldPath: string, newPath: string) => {
+    async (oldPath: string, newPath: string, kind?: 'file' | 'directory') => {
       if (!providerRef.current) return;
-      await providerRef.current.rename(oldPath, newPath);
-      if (selectedPath === oldPath) {
-        setSelectedPath(newPath);
+      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);
       }
-      await refresh();
     },
-    [refresh, selectedPath],
+    [selectedPath, entries, childEntries, expanded, loadRoot, loadChildren],
   );
 
   // Merge root entries with child entries for a flat tree representation
@@ -167,6 +340,7 @@ export function useFileTree(provider: FileSystemProvider | null): FileTreeState
     loading,
     toggleExpand,
     select,
+    reveal,
     createFile,
     createDirectory,
     deleteEntry,

package/src/Git/GitAuthGuidanceDialog.tsx

@@ -0,0 +1,84 @@
+/**
+ * GitAuthGuidanceDialog — shown when a git operation fails to authenticate.
+ *
+ * DocBlocks deliberately never collects or stores credentials, so this
+ * dialog only explains the three supported sign-in routes (credential
+ * helper, GitHub CLI, SSH key). The copy is exported as a standalone
+ * component so the clone dialog can embed it after an auth failure.
+ */
+
+import { maybeGetDocBlocksHost } from '@bendyline/docblocks/host';
+import { Dialog } from '../components/Dialog.js';
+
+const LEARN_MORE_URL =
+  'https://docs.github.com/en/get-started/getting-started-with-git/caching-your-github-credentials-in-git';
+
+const OPERATION_LABELS: Record<'push' | 'pull' | 'fetch' | 'clone' | 'pr', string> = {
+  push: 'push',
+  pull: 'pull',
+  fetch: 'fetch',
+  clone: 'clone',
+  pr: 'create the pull request',
+};
+
+/** The credential guidance copy, reusable outside this dialog (clone flow). */
+export function GitCredentialGuidance({ detail }: { detail?: string }) {
+  return (
+    <>
+      <p className="db-settings-hint">
+        DocBlocks never stores Git credentials. Sign in with one of these, then try again:
+      </p>
+      <ul className="db-git-hint">
+        <li>
+          A git credential helper (<code>git config credential.helper</code>)
+        </li>
+        <li>
+          The GitHub CLI (<code>gh auth login</code>)
+        </li>
+        <li>An SSH key registered with your remote</li>
+      </ul>
+      {detail && (
+        <details>
+          <summary>Details</summary>
+          <p className="db-git-hint">{detail}</p>
+        </details>
+      )}
+    </>
+  );
+}
+
+export function GitAuthGuidanceDialog({
+  operation,
+  detail,
+  onClose,
+}: {
+  operation: 'push' | 'pull' | 'fetch' | 'clone' | 'pr';
+  detail?: string;
+  onClose: () => void;
+}) {
+  return (
+    <Dialog
+      title="Git needs credentials"
+      onClose={onClose}
+      footer={
+        <>
+          <button
+            type="button"
+            className="db-git-secondary-btn"
+            onClick={() => void maybeGetDocBlocksHost()?.shell.openExternal(LEARN_MORE_URL)}
+          >
+            Learn more
+          </button>
+          <button type="button" className="db-git-primary-btn" onClick={onClose}>
+            Close
+          </button>
+        </>
+      }
+    >
+      <p className="db-settings-hint">
+        Git could not authenticate with the remote while trying to {OPERATION_LABELS[operation]}.
+      </p>
+      <GitCredentialGuidance detail={detail} />
+    </Dialog>
+  );
+}