@bendyline/docblocks-react 1.1.1 → 2.0.0

package/src/WorkspacePicker/WorkspacePicker.tsx

@@ -3,11 +3,18 @@
  * (IndexedDB-based or native folder via File System Access API).
  */
 
-import { useState, useEffect, useCallback, useRef } from 'react';
+import { Fragment, useState, useEffect, useCallback, useRef } from 'react';
 import type { WorkspaceDescriptor } from '@bendyline/docblocks/workspace';
 import { listWorkspaces, saveWorkspace, touchWorkspace } from '@bendyline/docblocks/workspace';
-import { isNativeFileSystemSupported } from '@bendyline/docblocks/filesystem';
 import { isElectronHost } from '@bendyline/docblocks/host';
+import { FolderIcon, NewFolderIcon } from '../icons.js';
+
+function isNativeFileSystemSupported(): boolean {
+  return (
+    typeof globalThis !== 'undefined' &&
+    typeof (globalThis as { showDirectoryPicker?: unknown }).showDirectoryPicker === 'function'
+  );
+}
 
 export interface WorkspacePickerProps {
   /** Currently active workspace id. */
@@ -16,14 +23,29 @@ export interface WorkspacePickerProps {
   onSelect: (descriptor: WorkspaceDescriptor) => void;
   /** Called when the user chooses "Open Folder" (native FS). */
   onOpenFolder: () => void;
+  /**
+   * Called when the user chooses "Clone Git repository". Only provided on
+   * the desktop when git is available — omitted, the item is hidden.
+   */
+  onCloneRepository?: () => void;
   /** Optional className. */
   className?: string;
 }
 
+function WorkspacePath({ path }: { path: string }) {
+  return path.split(/([\\/])/).map((segment, index) => (
+    <Fragment key={index}>
+      {segment}
+      {(segment === '\\' || segment === '/') && <wbr />}
+    </Fragment>
+  ));
+}
+
 export function WorkspacePicker({
   activeWorkspaceId,
   onSelect,
   onOpenFolder,
+  onCloneRepository,
   className,
 }: WorkspacePickerProps) {
   const [workspaces, setWorkspaces] = useState<WorkspaceDescriptor[]>([]);
@@ -82,6 +104,7 @@ export function WorkspacePicker({
   }, [workspaces.length, onSelect, refresh]);
 
   const activeWs = workspaces.find((w) => w.id === activeWorkspaceId);
+  const activeWorkspaceName = activeWs?.name ?? 'No workspace';
 
   return (
     <div ref={pickerRef} className={`db-workspace-picker ${className ?? ''}`}>
@@ -89,9 +112,16 @@ export function WorkspacePicker({
         className="db-workspace-picker-btn"
         onClick={() => setIsOpen(!isOpen)}
         title="Switch workspace"
+        aria-label={`Switch workspace, current: ${activeWorkspaceName}`}
       >
-        {activeWs?.name ?? 'No workspace'}
-        <span className="db-workspace-picker-caret">{isOpen ? '\u25B4' : '\u25BE'}</span>
+        <span className="db-workspace-picker-label">{activeWorkspaceName}</span>
+        <span className="db-workspace-picker-compact-icon">
+          <FolderIcon />
+        </span>
+        <span
+          className={`db-workspace-picker-caret${isOpen ? ' db-workspace-picker-caret--open' : ''}`}
+          aria-hidden="true"
+        />
       </button>
 
       {isOpen && (
@@ -104,9 +134,18 @@ export function WorkspacePicker({
               }`}
               onClick={() => handleSelect(ws)}
             >
-              {ws.name}
-              <span className="db-workspace-type">
-                {ws.type === 'native' || ws.type === 'electron-native' ? '(folder)' : ''}
+              <span className="db-workspace-details">
+                <span className="db-workspace-heading">
+                  <span>{ws.name}</span>
+                  {(ws.type === 'native' || ws.type === 'electron-native') && (
+                    <span className="db-workspace-type">(folder)</span>
+                  )}
+                </span>
+                {ws.rootPath && (
+                  <span className="db-workspace-path" title={ws.rootPath}>
+                    <WorkspacePath path={ws.rootPath} />
+                  </span>
+                )}
               </span>
             </button>
           ))}
@@ -115,7 +154,10 @@ export function WorkspacePicker({
 
           {!electron && (
             <button className="db-workspace-dropdown-item" onClick={handleCreateNew}>
-              + New Workspace
+              <span className="db-workspace-dropdown-action-label">
+                <NewFolderIcon />
+                <span>New Workspace</span>
+              </span>
             </button>
           )}
 
@@ -130,6 +172,18 @@ export function WorkspacePicker({
               Open Folder...
             </button>
           )}
+
+          {onCloneRepository && (
+            <button
+              className="db-workspace-dropdown-item"
+              onClick={() => {
+                setIsOpen(false);
+                onCloneRepository();
+              }}
+            >
+              Clone Git Repository...
+            </button>
+          )}
         </div>
       )}
     </div>

package/src/components/Dialog.tsx

@@ -0,0 +1,81 @@
+/**
+ * Dialog — shared modal primitive.
+ *
+ * Promotes the `db-dialog-overlay` / `db-dialog` pattern used by the
+ * settings dialogs into a reusable component, adding aria-modal and
+ * initial focus. Escape and (by default) backdrop clicks close it.
+ */
+
+import { useCallback, useEffect, useRef } from 'react';
+
+export interface DialogProps {
+  title: string;
+  onClose: () => void;
+  /** default 380px / wide 560px / full min(1100px, 94vw) column. */
+  size?: 'default' | 'wide' | 'full';
+  children: React.ReactNode;
+  /** Right-aligned action row below the body. */
+  footer?: React.ReactNode;
+  /** Element to focus on open; defaults to the close button. */
+  initialFocusRef?: React.RefObject<HTMLElement | null>;
+  /** Set false when a stray backdrop click would lose user input. */
+  closeOnBackdrop?: boolean;
+}
+
+export function Dialog({
+  title,
+  onClose,
+  size = 'default',
+  children,
+  footer,
+  initialFocusRef,
+  closeOnBackdrop = true,
+}: DialogProps) {
+  const closeButtonRef = useRef<HTMLButtonElement>(null);
+
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose();
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [onClose]);
+
+  useEffect(() => {
+    const target = initialFocusRef?.current ?? closeButtonRef.current;
+    target?.focus();
+    // Focus only on mount — refocusing on every re-render would fight the user.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const handleBackdropClick = useCallback(
+    (e: React.MouseEvent) => {
+      if (closeOnBackdrop && e.target === e.currentTarget) onClose();
+    },
+    [closeOnBackdrop, onClose],
+  );
+
+  const sizeClass =
+    size === 'wide' ? ' db-dialog--wide' : size === 'full' ? ' db-dialog--full' : '';
+
+  return (
+    <div className="db-dialog-overlay" onClick={handleBackdropClick}>
+      <div className={`db-dialog${sizeClass}`} role="dialog" aria-modal="true" aria-label={title}>
+        <div className="db-dialog-header">
+          <h2 className="db-dialog-title">{title}</h2>
+          <button
+            ref={closeButtonRef}
+            type="button"
+            className="db-dialog-close"
+            onClick={onClose}
+            aria-label="Close"
+          >
+            &times;
+          </button>
+        </div>
+        <div className="db-dialog-body">{children}</div>
+        {footer && <div className="db-dialog-footer">{footer}</div>}
+      </div>
+    </div>
+  );
+}

package/src/editor.ts

@@ -0,0 +1,72 @@
+/**
+ * Placeholder prompts shown by DocBlocks when a Markdown document is empty.
+ * Hosts pick one prompt for each mounted document generation and pass it to
+ * Squisq, so the copy remains stable while that document is open.
+ */
+export const EMPTY_DOCUMENT_PROMPTS = [
+  'Start typing your content, or drop images on top of me...',
+  'Write anything -- paste markdown, drag in images, or just start typing...',
+  'Type away. Markdown syntax works too...',
+  'Chapter 1 begins here...',
+  'Once upon a time...',
+  "A blank page. Exciting, isn't it?",
+  'The first word is always the hardest...',
+  'Plot twist: this is where it all starts...',
+  'Write something the future you will thank you for...',
+  'Begin at the beginning...',
+  "Let's begin.",
+  'We can be heroes...',
+  'Here comes the sun...',
+  'And so it begins...',
+  'Let it be, let it be...',
+  "Don't stop believing...",
+  'Started from the bottom...',
+  'This is the start of something new...',
+  'Ground control to Major Tom...',
+  'Come as you are...',
+  'Every new beginning...',
+  "Hello, is it me you're looking for?",
+  'Imagine all the people...',
+  'Anything you want, you got it...',
+  'Rise above...',
+  'Do you have the time...',
+  'Here we are now, entertain us...',
+  'All the small things...',
+  'Should I stay or should I go?',
+  'I am a patient boy -- I wait, I wait, I wait...',
+  'Destination unknown...',
+  'Easy like Sunday morning...',
+  'Dance, dance, dance to the radio...',
+  'New day rising...',
+  'Visit the world...',
+  'Positive mental attitude...',
+  'Better I sing than I cry...',
+  'Disconnect for a minute...',
+  'We need new noise...',
+  'Shoot the moon...',
+  "I'll surprise you sometime -- I'll come around...",
+  'Coming out of my cage, and doing just fine...',
+  "Throw me to the wolves -- I'll come back, leading the pack...",
+  'There comes a time -- no excuses...',
+  "It's up to me now, turn on the bright lights...",
+  'Do what you want...',
+  'Fingers crossed...',
+  'This is the start of how it all ends...',
+  'It has to start somewhere, it has to start sometime -- what better place than here? what better time than now?',
+  "I know myself, and I'll begin again...",
+  'Dig me out, dig me in...',
+  "Everybody's full of sugar, honey, ice and tea...",
+  "Take time with a wounded hand, 'cause it likes to heal...",
+  'Grab a brush and put on a little makeup...',
+  'Amber is the color of your energy...',
+  "Wait -- they don't love it like I love it...",
+  "A world's been buried, where love is the law; a you-topia...",
+] as const;
+
+export type EmptyDocumentPrompt = (typeof EMPTY_DOCUMENT_PROMPTS)[number];
+
+/** Pick a prompt using the supplied random source, or `Math.random`. */
+export function pickEmptyDocumentPrompt(random: () => number = Math.random): EmptyDocumentPrompt {
+  const index = Math.floor(random() * EMPTY_DOCUMENT_PROMPTS.length);
+  return EMPTY_DOCUMENT_PROMPTS[index] ?? EMPTY_DOCUMENT_PROMPTS[0];
+}

package/src/hooks/index.ts

@@ -1 +1,2 @@
-export { useAutoSave } from './useAutoSave.js';
+export { useDocumentSession } from './useDocumentSession.js';
+export type { UseDocumentSessionResult } from './useDocumentSession.js';

package/src/hooks/useDocumentSession.ts

@@ -0,0 +1,37 @@
+import { useState, useSyncExternalStore } from 'react';
+import {
+  DocumentRecoveryJournal,
+  DocumentSession,
+  getDefaultDocumentRecoveryStorage,
+  type DocumentSessionSnapshot,
+} from '@bendyline/docblocks/document';
+
+export interface UseDocumentSessionResult {
+  /** Stable controller for the lifetime of the mounted shell/panel. */
+  session: DocumentSession;
+  /** React snapshot of dirty/saving/saved/error/conflict state. */
+  snapshot: DocumentSessionSnapshot;
+}
+
+/**
+ * React binding for the framework-neutral DocumentSession engine.
+ *
+ * The hook deliberately does not infer target transitions from props.
+ * Callers must use transitionTo(), retarget(), or delete() before changing
+ * their view state so persistence ordering remains explicit.
+ */
+export function useDocumentSession(autoSaveDelayMs = 500): UseDocumentSessionResult {
+  const [session] = useState(
+    () =>
+      new DocumentSession({
+        autoSaveDelayMs,
+        recoveryJournal: new DocumentRecoveryJournal(getDefaultDocumentRecoveryStorage()),
+      }),
+  );
+  const snapshot = useSyncExternalStore(
+    session.subscribe,
+    session.getSnapshot,
+    session.getSnapshot,
+  );
+  return { session, snapshot };
+}

package/src/icons.tsx

@@ -1,70 +1,48 @@
-import type { SVGProps } from 'react';
+/**
+ * DocBlocks shell icons use the Font Awesome Free webfont bundled by
+ * `@bendyline/squisq-editor-react/styles`. Controls provide the accessible
+ * name, so the glyphs themselves stay decorative.
+ */
 
-const defaults: SVGProps<SVGSVGElement> = {
-  width: 16,
-  height: 16,
-  viewBox: '0 0 16 16',
-  fill: 'none',
-  stroke: 'currentColor',
-  strokeWidth: 1.5,
-  strokeLinecap: 'round' as const,
-  strokeLinejoin: 'round' as const,
-};
+function FontAwesomeIcon({ icon }: { icon: string }) {
+  return <i className={icon} aria-hidden="true" />;
+}
 
-export function NewFileIcon(props: SVGProps<SVGSVGElement>) {
-  return (
-    <svg {...defaults} {...props}>
-      {/* Page outline */}
-      <path d="M9.5 1.5H4a1 1 0 0 0-1 1v11a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1V5l-3.5-3.5Z" />
-      {/* Fold */}
-      <path d="M9.5 1.5V5H13" />
-      {/* Plus sign */}
-      <line x1="6.5" y1="10" x2="9.5" y2="10" />
-      <line x1="8" y1="8.5" x2="8" y2="11.5" />
-    </svg>
-  );
+export function NewFileIcon() {
+  return <FontAwesomeIcon icon="fa-solid fa-file-circle-plus" />;
 }
 
-export function NewFolderIcon(props: SVGProps<SVGSVGElement>) {
-  return (
-    <svg {...defaults} {...props}>
-      {/* Folder outline */}
-      <path d="M2 3.5a1 1 0 0 1 1-1h3l1.5 1.5H13a1 1 0 0 1 1 1v7a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3.5Z" />
-      {/* Plus sign */}
-      <line x1="6" y1="8.5" x2="10" y2="8.5" />
-      <line x1="8" y1="6.5" x2="8" y2="10.5" />
-    </svg>
-  );
+export function NewFolderIcon() {
+  return <FontAwesomeIcon icon="fa-solid fa-folder-plus" />;
 }
 
-export function RefreshIcon(props: SVGProps<SVGSVGElement>) {
-  return (
-    <svg {...defaults} {...props}>
-      <path d="M13.5 8A5.5 5.5 0 1 1 8 2.5" />
-      <polyline points="13.5 3 13.5 6.5 10 6.5" />
-    </svg>
-  );
+export function FolderIcon() {
+  return <FontAwesomeIcon icon="fa-solid fa-folder" />;
 }
 
-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 MoreIcon() {
+  return <FontAwesomeIcon icon="fa-solid fa-ellipsis" />;
+}
+
+export function WorkspaceIcon() {
+  return <FontAwesomeIcon icon="fa-solid fa-gear" />;
 }
 
-export function WorkspaceIcon(props: SVGProps<SVGSVGElement>) {
+export function SplitViewIcon() {
   return (
-    <svg {...defaults} {...props}>
-      {/* Desk surface (top-down rectangle) */}
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
       <rect x="1.5" y="2.5" width="13" height="11" rx="1" />
-      {/* Blotter/pad with two vertical lines */}
-      <rect x="4" y="4.5" width="8" height="7" rx="0.5" />
-      <line x1="6.5" y1="5.5" x2="6.5" y2="10.5" strokeWidth="1" />
-      <line x1="9.5" y1="5.5" x2="9.5" y2="10.5" strokeWidth="1" />
+      <line x1="6" y1="2.5" x2="6" y2="13.5" />
     </svg>
   );
 }

package/src/index.ts

@@ -4,7 +4,11 @@
 
 // FileExplorer
 export { FileExplorer } from './FileExplorer/index.js';
-export type { FileExplorerProps } from './FileExplorer/index.js';
+export type {
+  FileExplorerProps,
+  FileTreeChange,
+  FileTreeMutationHandler,
+} from './FileExplorer/index.js';
 export { FileTreeNode } from './FileExplorer/index.js';
 export type { FileTreeNodeProps } from './FileExplorer/index.js';
 export { useFileTree } from './FileExplorer/index.js';
@@ -19,13 +23,39 @@ export type { DocBlocksShellProps } from './DocBlocksShell/index.js';
 
 // AppMenu
 export { AppMenu } from './AppMenu/index.js';
-export type { AppMenuProps, ThemePreference } from './AppMenu/index.js';
+export type { AccentColor, AppMenuProps, ThemePreference } from './AppMenu/index.js';
+
+// Settings
+export { AccentColorSettings, SettingsDialog, ThemeSettings } from './Settings/public-api.js';
+export type {
+  AccentColorSettingsProps,
+  SettingsDialogProps,
+  ThemeSettingsProps,
+} from './Settings/public-api.js';
 
 // Export
-export { ExportToolbarControls } from './Export/index.js';
-export type { ExportToolbarControlsProps, ExportFormat, ExportOptions } from './Export/index.js';
+export {
+  buildExportFilename,
+  DEFAULT_OPTIONS,
+  loadLastExportOptions,
+  runExport,
+  updateExportTargetExtension,
+  ExportToolbarControls,
+} from './Export/index.js';
+export type {
+  ExportDestinationControl,
+  ExportDestinationAdapter,
+  ExportDestinationTarget,
+  ExportToolbarControlsProps,
+  ExportFormat,
+  HtmlBundle,
+  HtmlStyle,
+  ExportOptions,
+  ExportBlobSaver,
+} from './Export/index.js';
 export { ExportDialog } from './Export/index.js';
 export type { ExportDialogProps } from './Export/index.js';
 
 // Hooks
-export { useAutoSave } from './hooks/index.js';
+export { useDocumentSession } from './hooks/index.js';
+export type { UseDocumentSessionResult } from './hooks/index.js';

package/src/preferences/theme.ts

@@ -0,0 +1,67 @@
+/** Appearance preferences shared by the shell and settings UI. */
+
+export type ThemePreference = 'auto' | 'light' | 'dark';
+
+export const ACCENT_COLORS = [
+  'brown',
+  'green',
+  'blue',
+  'purple',
+  'maroon',
+  'orange',
+  'gray',
+] as const;
+
+export type AccentColor = (typeof ACCENT_COLORS)[number];
+
+/**
+ * Chrome (titlebar) background per resolved theme. Keep in sync with
+ * `--db-bg-subtle` for the default accent in styles/docblocks.css and with
+ * the static `<meta name="theme-color">` values in the site's index.html.
+ * The shell writes these into the theme-color metas so the installed web
+ * app's titlebar (Window Controls Overlay caption area, Android status bar)
+ * follows the resolved theme.
+ */
+export const DB_CHROME_COLORS: Record<'light' | 'dark', string> = {
+  light: '#f3eede',
+  dark: '#262219',
+};
+
+const THEME_STORAGE_KEY = 'docblocks:themePreference';
+const ACCENT_STORAGE_KEY = 'docblocks:accentColor';
+
+export function loadThemePreference(): ThemePreference {
+  try {
+    const raw = localStorage.getItem(THEME_STORAGE_KEY);
+    if (raw === 'light' || raw === 'dark' || raw === 'auto') return raw;
+  } catch {
+    // ignore unavailable storage
+  }
+  return 'auto';
+}
+
+export function saveThemePreference(value: ThemePreference): void {
+  try {
+    localStorage.setItem(THEME_STORAGE_KEY, value);
+  } catch {
+    // ignore quota errors
+  }
+}
+
+export function loadAccentColor(): AccentColor {
+  try {
+    const raw = localStorage.getItem(ACCENT_STORAGE_KEY);
+    if (ACCENT_COLORS.some((color) => color === raw)) return raw as AccentColor;
+  } catch {
+    // ignore unavailable storage
+  }
+  return 'brown';
+}
+
+export function saveAccentColor(value: AccentColor): void {
+  try {
+    localStorage.setItem(ACCENT_STORAGE_KEY, value);
+  } catch {
+    // ignore quota errors
+  }
+}

package/src/provider-lease.ts

@@ -0,0 +1,52 @@
+import type { FileSystemProviderV2 } from '@bendyline/docblocks/filesystem';
+
+interface ProviderLeaseRecord {
+  holders: number;
+  generation: number;
+  disposePromise: Promise<void> | null;
+}
+
+const leases = new WeakMap<FileSystemProviderV2, ProviderLeaseRecord>();
+
+/**
+ * Retain one UI ownership lease for a provider.
+ *
+ * Final release is deferred by one microtask. React Strict Mode intentionally
+ * performs setup → cleanup → setup, so an immediate cleanup disposer would
+ * permanently close the provider that the second setup still owns.
+ */
+export function retainFileSystemProvider(provider: FileSystemProviderV2): () => void {
+  let record = leases.get(provider);
+  if (!record) {
+    record = { holders: 0, generation: 0, disposePromise: null };
+    leases.set(provider, record);
+  }
+  if (record.disposePromise) {
+    throw new Error('Cannot retain a filesystem provider after disposal has started.');
+  }
+
+  record.holders += 1;
+  record.generation += 1;
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    record!.holders -= 1;
+    record!.generation += 1;
+    const releaseGeneration = record!.generation;
+    queueMicrotask(() => {
+      if (
+        record!.holders !== 0 ||
+        record!.generation !== releaseGeneration ||
+        record!.disposePromise
+      ) {
+        return;
+      }
+      record!.disposePromise = provider.dispose();
+      // React cleanup cannot await or render a disposal failure. Joiners still
+      // receive the original promise from the provider; this observer prevents
+      // an unhandled rejection during unmount.
+      void record!.disposePromise.catch(() => undefined);
+    });
+  };
+}