@bendyline/docblocks-react 1.0.0 → 1.1.1

package/src/hooks/useAutoSave.ts

@@ -2,57 +2,115 @@
  * useAutoSave — debounced auto-save hook.
  *
  * Writes content to the FileSystemProvider after a delay
- * whenever the content changes.
+ * whenever the content changes. Returns a `flush` function so callers
+ * (e.g. an explicit Ctrl/Cmd+S handler) can force an immediate write
+ * and await its completion.
  */
 
 import { useEffect, useRef, useCallback } from 'react';
 import type { FileSystemProvider } from '@bendyline/docblocks/filesystem';
 
+export interface UseAutoSaveResult {
+  /** Cancel any pending debounce and write the current content immediately. */
+  flush: () => Promise<void>;
+}
+
 export function useAutoSave(
   provider: FileSystemProvider | null,
   filePath: string | null,
   content: string,
   delayMs = 500,
-): void {
+  onSaved?: (filePath: string, content: string) => void,
+): UseAutoSaveResult {
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const lastSavedRef = useRef<string>(content);
-
-  const save = useCallback(async () => {
-    if (!provider || !filePath) return;
-    if (content === lastSavedRef.current) return;
-    lastSavedRef.current = content;
-    await provider.writeFile(filePath, content);
-  }, [provider, filePath, content]);
-
-  useEffect(() => {
-    if (!provider || !filePath) return;
+  const contentRef = useRef(content);
+  const onSavedRef = useRef(onSaved);
+  const targetRef = useRef<{
+    provider: FileSystemProvider;
+    filePath: string;
+    lastSaved: string;
+  } | null>(null);
 
+  const clearTimer = useCallback(() => {
     if (timerRef.current) {
       clearTimeout(timerRef.current);
+      timerRef.current = null;
     }
+  }, []);
 
-    timerRef.current = setTimeout(() => {
-      save();
-    }, delayMs);
+  const flushTarget = useCallback(
+    async (
+      target: {
+        provider: FileSystemProvider;
+        filePath: string;
+        lastSaved: string;
+      },
+      nextContent: string,
+    ) => {
+      if (nextContent === target.lastSaved) return;
+      const previous = target.lastSaved;
+      target.lastSaved = nextContent;
+      try {
+        await target.provider.writeFile(target.filePath, nextContent);
+        onSavedRef.current?.(target.filePath, nextContent);
+      } catch (err) {
+        target.lastSaved = previous;
+        throw err;
+      }
+    },
+    [],
+  );
+
+  useEffect(() => {
+    onSavedRef.current = onSaved;
+  }, [onSaved]);
+
+  useEffect(() => {
+    contentRef.current = content;
+  }, [content]);
+
+  useEffect(() => {
+    clearTimer();
+    targetRef.current = provider && filePath ? { provider, filePath, lastSaved: content } : null;
+    contentRef.current = content;
 
     return () => {
-      if (timerRef.current) {
-        clearTimeout(timerRef.current);
+      clearTimer();
+      const target = targetRef.current;
+      if (target) {
+        void flushTarget(target, contentRef.current).catch(() => undefined);
       }
+      targetRef.current = null;
     };
-  }, [content, delayMs, save, provider, filePath]);
+    // `content` is intentionally captured only when the save target changes.
+    // Content edits are handled by the debounced effect below.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [provider, filePath, clearTimer, flushTarget]);
 
-  // Flush on unmount
   useEffect(() => {
+    const target = targetRef.current;
+    if (!target) return;
+    clearTimer();
+
+    if (content !== target.lastSaved) {
+      timerRef.current = setTimeout(() => {
+        const currentTarget = targetRef.current;
+        if (!currentTarget) return;
+        void flushTarget(currentTarget, contentRef.current).catch(() => undefined);
+      }, delayMs);
+    }
+
     return () => {
-      if (timerRef.current) {
-        clearTimeout(timerRef.current);
-      }
-      // Sync save on unmount is best-effort
-      if (provider && filePath && content !== lastSavedRef.current) {
-        provider.writeFile(filePath, content);
-      }
+      clearTimer();
     };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
+  }, [content, delayMs, clearTimer, flushTarget]);
+
+  const flush = useCallback(async () => {
+    clearTimer();
+    const target = targetRef.current;
+    if (!target) return;
+    await flushTarget(target, contentRef.current);
+  }, [clearTimer, flushTarget]);
+
+  return { flush };
 }

package/src/icons.tsx

@@ -46,6 +46,16 @@ export function RefreshIcon(props: SVGProps<SVGSVGElement>) {
   );
 }
 
+export function MoreIcon(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg {...defaults} {...props}>
+      <circle cx="3.5" cy="8" r="1" fill="currentColor" stroke="none" />
+      <circle cx="8" cy="8" r="1" fill="currentColor" stroke="none" />
+      <circle cx="12.5" cy="8" r="1" fill="currentColor" stroke="none" />
+    </svg>
+  );
+}
+
 export function WorkspaceIcon(props: SVGProps<SVGSVGElement>) {
   return (
     <svg {...defaults} {...props}>

package/src/index.ts

@@ -19,7 +19,7 @@ export type { DocBlocksShellProps } from './DocBlocksShell/index.js';
 
 // AppMenu
 export { AppMenu } from './AppMenu/index.js';
-export type { AppMenuProps } from './AppMenu/index.js';
+export type { AppMenuProps, ThemePreference } from './AppMenu/index.js';
 
 // Export
 export { ExportToolbarControls } from './Export/index.js';

package/src/preferences/versioning.ts

@@ -0,0 +1,69 @@
+/**
+ * Versioning preferences — global default + per-workspace resolution.
+ *
+ * The global preference controls whether DocBlocks writes version
+ * snapshots (under `<basename>_files/.versions/`) when editing. The
+ * default is `'browser-only'` so local-folder workspaces stay clean by
+ * default and only IndexedDB workspaces accumulate version history.
+ *
+ * Each workspace can override the global default with its own setting
+ * stored on the WorkspaceDescriptor. `'inherit'` (or absent) defers to
+ * the global preference; `'on'` / `'off'` force the behavior regardless.
+ */
+
+import type { WorkspaceDescriptor } from '@bendyline/docblocks/workspace';
+
+export type VersioningPreference = 'on' | 'browser-only' | 'off';
+
+const STORAGE_KEY = 'docblocks:versioningPreference';
+const DEFAULT_PREFERENCE: VersioningPreference = 'browser-only';
+
+export function loadVersioningPreference(): VersioningPreference {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (raw === 'on' || raw === 'browser-only' || raw === 'off') return raw;
+  } catch {
+    // ignore
+  }
+  return DEFAULT_PREFERENCE;
+}
+
+export function saveVersioningPreference(value: VersioningPreference): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, value);
+  } catch {
+    // ignore quota errors
+  }
+}
+
+/** Whether a workspace type is "local" (writes to a real folder on disk). */
+export function isLocalWorkspaceType(type: WorkspaceDescriptor['type']): boolean {
+  return type === 'native' || type === 'electron-native';
+}
+
+/**
+ * Compute the effective versioning state for a workspace, honoring the
+ * per-workspace override first and falling back to the global preference.
+ *
+ * Returns `false` whenever no workspace is provided so callers can use
+ * this directly during initial render before a workspace loads.
+ */
+export function resolveVersioningEnabled(
+  workspace: WorkspaceDescriptor | null,
+  globalPref: VersioningPreference,
+): boolean {
+  if (!workspace) return false;
+
+  const override = workspace.versioningOverride;
+  if (override === 'on') return true;
+  if (override === 'off') return false;
+
+  switch (globalPref) {
+    case 'on':
+      return true;
+    case 'off':
+      return false;
+    case 'browser-only':
+      return !isLocalWorkspaceType(workspace.type);
+  }
+}