@bendyline/docblocks-react 1.1.2 → 2.0.0

package/src/Git/useGitStatus.ts

@@ -0,0 +1,78 @@
+/**
+ * useGitStatus — subscribes to the host's owner-scoped repository stream.
+ *
+ * Dedupes identical payloads so a permanently-dirty working tree (normal
+ * under the manual-commit model) doesn't repaint the tree on every push
+ * from the main process.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { DocBlocksHostGitAPI, GitStatus } from '@bendyline/docblocks/host';
+
+const SCHEDULE_REFRESH_MS = 1500;
+
+function statusKey(status: GitStatus): string {
+  return JSON.stringify(status);
+}
+
+export interface UseGitStatusResult {
+  status: GitStatus | null;
+  /** Fetch a fresh status immediately (after a renderer-initiated git op). */
+  refresh: () => void;
+  /** Trailing-debounced refresh (after autosave writes). */
+  scheduleRefresh: () => void;
+}
+
+export function useGitStatus(
+  gitApi: DocBlocksHostGitAPI | null,
+  repositoryId: string | null,
+  enabled: boolean,
+): UseGitStatusResult {
+  const [status, setStatus] = useState<GitStatus | null>(null);
+  const lastKeyRef = useRef<string | null>(null);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const apply = useCallback((next: GitStatus) => {
+    const key = statusKey(next);
+    if (key === lastKeyRef.current) return;
+    lastKeyRef.current = key;
+    setStatus(next);
+  }, []);
+
+  useEffect(() => {
+    lastKeyRef.current = null;
+    setStatus(null);
+    if (!gitApi || !repositoryId || !enabled) return;
+    let cancelled = false;
+    const unsubscribe = gitApi.onStatusChanged(repositoryId, (next) => {
+      if (!cancelled) apply(next);
+    });
+    return () => {
+      cancelled = true;
+      unsubscribe();
+    };
+  }, [gitApi, repositoryId, enabled, apply]);
+
+  const refresh = useCallback(() => {
+    if (!gitApi || !repositoryId || !enabled) return;
+    void gitApi.status(repositoryId).then((result) => {
+      if (result.ok) apply(result.value);
+    });
+  }, [gitApi, repositoryId, enabled, apply]);
+
+  const scheduleRefresh = useCallback(() => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+    timerRef.current = setTimeout(() => {
+      timerRef.current = null;
+      refresh();
+    }, SCHEDULE_REFRESH_MS);
+  }, [refresh]);
+
+  useEffect(() => {
+    return () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    };
+  }, []);
+
+  return { status, refresh, scheduleRefresh };
+}

package/src/Settings/Settings.tsx

@@ -0,0 +1,118 @@
+/** Shared controls used by the app and host-specific DocBlocks settings dialogs. */
+
+import type { ReactNode } from 'react';
+import { Dialog } from '../components/Dialog.js';
+import { ACCENT_COLORS, type AccentColor, type ThemePreference } from '../preferences/theme.js';
+
+export type { AccentColor, ThemePreference } from '../preferences/theme.js';
+
+const ACCENT_LABELS: Record<AccentColor, string> = {
+  brown: 'Brown',
+  green: 'Green',
+  blue: 'Blue',
+  purple: 'Purple',
+  maroon: 'Maroon',
+  orange: 'Orange',
+  gray: 'Gray',
+};
+
+export interface SettingsDialogProps {
+  title?: string;
+  onClose: () => void;
+  children: ReactNode;
+}
+
+export function SettingsDialog({ title = 'Settings', onClose, children }: SettingsDialogProps) {
+  return (
+    <Dialog title={title} onClose={onClose}>
+      {children}
+    </Dialog>
+  );
+}
+
+export interface ThemeSettingsProps {
+  value: ThemePreference;
+  onChange: (theme: ThemePreference) => void;
+  name?: string;
+}
+
+export function ThemeSettings({ value, onChange, name = 'theme' }: ThemeSettingsProps) {
+  return (
+    <fieldset className="db-settings-fieldset">
+      <legend className="db-settings-legend">Theme</legend>
+      <label className="db-settings-radio">
+        <input
+          type="radio"
+          name={name}
+          value="auto"
+          checked={value === 'auto'}
+          onChange={() => onChange('auto')}
+        />
+        System default
+      </label>
+      <label className="db-settings-radio">
+        <input
+          type="radio"
+          name={name}
+          value="light"
+          checked={value === 'light'}
+          onChange={() => onChange('light')}
+        />
+        Light
+      </label>
+      <label className="db-settings-radio">
+        <input
+          type="radio"
+          name={name}
+          value="dark"
+          checked={value === 'dark'}
+          onChange={() => onChange('dark')}
+        />
+        Dark
+      </label>
+    </fieldset>
+  );
+}
+
+export interface AccentColorSettingsProps {
+  value: AccentColor;
+  onChange: (color: AccentColor) => void;
+  name?: string;
+}
+
+export function AccentColorSettings({
+  value,
+  onChange,
+  name = 'accent-color',
+}: AccentColorSettingsProps) {
+  return (
+    <fieldset className="db-settings-fieldset">
+      <legend className="db-settings-legend">Accent color</legend>
+      <p className="db-settings-hint">Used in both light and dark appearances.</p>
+      <div className="db-settings-accent-grid">
+        {ACCENT_COLORS.map((color) => (
+          <label
+            className={`db-settings-accent${
+              value === color ? ' db-settings-accent--selected' : ''
+            }`}
+            key={color}
+          >
+            <input
+              className="db-settings-accent-input"
+              type="radio"
+              name={name}
+              value={color}
+              checked={value === color}
+              onChange={() => onChange(color)}
+            />
+            <span
+              className={`db-settings-accent-swatch db-settings-accent-swatch--${color}`}
+              aria-hidden="true"
+            />
+            <span>{ACCENT_LABELS[color]}</span>
+          </label>
+        ))}
+      </div>
+    </fieldset>
+  );
+}

package/src/Settings/public-api.ts

@@ -0,0 +1,8 @@
+export { AccentColorSettings, SettingsDialog, ThemeSettings } from './Settings.js';
+export type {
+  AccentColor,
+  AccentColorSettingsProps,
+  SettingsDialogProps,
+  ThemePreference,
+  ThemeSettingsProps,
+} from './Settings.js';

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>
   );
 }