@bendyline/docblocks-react 1.1.2 → 2.0.0

package/src/DocBlocksShell/LazyEditorShell.ts

@@ -0,0 +1,2 @@
+/** Deferred boundary for the large Squisq editor implementation. */
+export { EditorShell as default } from '@bendyline/squisq-editor-react';

package/src/DocBlocksShell/UpdateAvailableNotice.tsx

@@ -0,0 +1,60 @@
+import { useState } from 'react';
+
+const UPDATE_PROMPT_ID = 'db-update-available-prompt';
+
+export interface UpdateAvailableNoticeProps {
+  available: boolean;
+  onApplyUpdate?: () => void;
+  blocked?: boolean;
+  statusBarVisible: boolean;
+}
+
+/**
+ * Keeps PWA updates unobtrusive until the user asks to review one. The
+ * notice is positioned over the editor status bar by DocBlocksShell CSS;
+ * the existing Reload/Later prompt remains a fixed shell-level card.
+ */
+export function UpdateAvailableNotice({
+  available,
+  onApplyUpdate,
+  blocked = false,
+  statusBarVisible,
+}: UpdateAvailableNoticeProps) {
+  const [promptOpen, setPromptOpen] = useState(false);
+
+  if (!available || !onApplyUpdate) return null;
+
+  const promptVisible = promptOpen && !blocked;
+
+  return (
+    <>
+      <button
+        type="button"
+        className={`db-update-status-notice${
+          statusBarVisible ? '' : ' db-update-status-notice--floating'
+        }`}
+        onClick={() => setPromptOpen(true)}
+        disabled={blocked}
+        aria-controls={UPDATE_PROMPT_ID}
+        aria-expanded={promptVisible}
+        aria-label="A new version of DocBlocks is available. Show update options."
+        title="A new version of DocBlocks is available"
+      >
+        Update available
+      </button>
+      {promptVisible && (
+        <div id={UPDATE_PROMPT_ID} className="db-update-banner" role="alert">
+          <span>A new version of DocBlocks is available.</span>
+          <div className="db-update-banner-actions">
+            <button type="button" onClick={onApplyUpdate}>
+              Reload
+            </button>
+            <button type="button" onClick={() => setPromptOpen(false)}>
+              Later
+            </button>
+          </div>
+        </div>
+      )}
+    </>
+  );
+}

package/src/DocBlocksShell/document-title.ts

@@ -0,0 +1,19 @@
+import { useEffect } from 'react';
+
+const APP_TITLE = 'DocBlocks';
+
+export function titleForSelectedFile(selectedFile: string | null): string {
+  if (!selectedFile) return APP_TITLE;
+
+  const filename = selectedFile.replace(/^\/+/, '').split('/').pop();
+  const name = filename?.replace(/\.[^.]+$/, '');
+  return name ? `${name} - ${APP_TITLE}` : APP_TITLE;
+}
+
+export function useDocumentTitle(selectedFile: string | null): void {
+  useEffect(() => {
+    if (typeof document !== 'undefined') {
+      document.title = titleForSelectedFile(selectedFile);
+    }
+  }, [selectedFile]);
+}

package/src/DocBlocksShell/workspace-authority-barrier.ts

@@ -0,0 +1,26 @@
+/**
+ * Renderer-side barrier for main-authoritative Electron workspace identity.
+ * OS requests may arrive before IndexedDB descriptors have been reconciled;
+ * they must retain navigation priority while waiting for that reconciliation.
+ */
+export class WorkspaceAuthorityBarrier {
+  private ready = false;
+  private readonly readyPromise: Promise<void>;
+  private resolveReady!: () => void;
+
+  public constructor() {
+    this.readyPromise = new Promise<void>((resolve) => {
+      this.resolveReady = resolve;
+    });
+  }
+
+  public markReady(): void {
+    if (this.ready) return;
+    this.ready = true;
+    this.resolveReady();
+  }
+
+  public wait(): Promise<void> {
+    return this.readyPromise;
+  }
+}

package/src/Export/DeferredExportToolbarControls.tsx

@@ -0,0 +1,23 @@
+import { lazy, Suspense } from 'react';
+import type {
+  ExportDestinationAdapter,
+  ExportDestinationTarget,
+  ExportToolbarControlsProps,
+} from './ExportToolbarControls.js';
+
+const ExportToolbarControlsImplementation = lazy(() =>
+  import('./ExportToolbarControls.js').then((module) => ({
+    default: module.ExportToolbarControls,
+  })),
+);
+
+/** Public toolbar control with its editor-coupled implementation deferred. */
+export function ExportToolbarControls(props: ExportToolbarControlsProps) {
+  return (
+    <Suspense fallback={null}>
+      <ExportToolbarControlsImplementation {...props} />
+    </Suspense>
+  );
+}
+
+export type { ExportDestinationAdapter, ExportDestinationTarget, ExportToolbarControlsProps };

package/src/Export/ExportDialog.tsx

@@ -2,7 +2,7 @@
  * ExportDialog — modal for choosing export format and options.
  */
 
-import { useState, useCallback, useEffect, useRef } from 'react';
+import { useState, useCallback, useEffect, useMemo, useRef } from 'react';
 import { getThemeSummaries } from '@bendyline/squisq/schemas';
 import type { ExportFormat, ExportOptions, HtmlBundle, HtmlStyle } from './export-options.js';
 import { FORMAT_LABELS, saveExportOptions } from './export-options.js';
@@ -13,12 +13,22 @@ export interface ExportDialogProps {
   initial: ExportOptions;
   /** Whether the export is currently running. */
   exporting: boolean;
+  /** Optional host-provided destination path control. */
+  destination?: ExportDestinationControl;
   /** Called when the user confirms the export. */
   onExport: (options: ExportOptions) => void;
+  /** Called whenever the currently selected options change. */
+  onOptionsChange?: (options: ExportOptions) => void;
   /** Called when the dialog is dismissed. */
   onClose: () => void;
 }
 
+export interface ExportDestinationControl {
+  value: string;
+  onPick: (options: ExportOptions) => void | Promise<void>;
+  hint?: string;
+}
+
 const FORMATS: ExportFormat[] = ['pdf', 'docx', 'pptx', 'html', 'md'];
 
 /** Short labels for the Format chip row. The fuller `FORMAT_LABELS` list
@@ -96,7 +106,14 @@ function ChipRadioGroup<T extends string>({
   );
 }
 
-export function ExportDialog({ initial, exporting, onExport, onClose }: ExportDialogProps) {
+export function ExportDialog({
+  initial,
+  exporting,
+  destination,
+  onExport,
+  onOptionsChange,
+  onClose,
+}: ExportDialogProps) {
   const [format, setFormat] = useState<ExportFormat>(initial.format);
   const [themeId, setThemeId] = useState(initial.themeId);
   const [transformStyle, setTransformStyle] = useState(initial.transformStyle);
@@ -156,8 +173,8 @@ export function ExportDialog({ initial, exporting, onExport, onClose }: ExportDi
     };
   }, [showTransform]);
 
-  const handleExport = useCallback(() => {
-    const opts: ExportOptions = {
+  const currentOptions = useMemo<ExportOptions>(
+    () => ({
       format,
       themeId,
       transformStyle,
@@ -166,22 +183,29 @@ export function ExportDialog({ initial, exporting, onExport, onClose }: ExportDi
       htmlBundle,
       includeLinkedDocs: showIncludeLinked && includeLinkedDocs,
       entryAsIndex: showEntryAsIndex && entryAsIndex,
-    };
-    saveExportOptions(opts);
-    onExport(opts);
-  }, [
-    format,
-    themeId,
-    transformStyle,
-    pageSize,
-    htmlStyle,
-    htmlBundle,
-    includeLinkedDocs,
-    entryAsIndex,
-    showIncludeLinked,
-    showEntryAsIndex,
-    onExport,
-  ]);
+    }),
+    [
+      format,
+      themeId,
+      transformStyle,
+      pageSize,
+      htmlStyle,
+      htmlBundle,
+      includeLinkedDocs,
+      entryAsIndex,
+      showIncludeLinked,
+      showEntryAsIndex,
+    ],
+  );
+
+  useEffect(() => {
+    onOptionsChange?.(currentOptions);
+  }, [currentOptions, onOptionsChange]);
+
+  const handleExport = useCallback(() => {
+    saveExportOptions(currentOptions);
+    onExport(currentOptions);
+  }, [currentOptions, onExport]);
 
   // Close on Escape
   useEffect(() => {
@@ -226,6 +250,36 @@ export function ExportDialog({ initial, exporting, onExport, onClose }: ExportDi
             />
           </div>
 
+          {destination && (
+            <div className="db-export-field">
+              <label className="db-export-label" htmlFor="db-export-path">
+                Export to
+              </label>
+              <div className="db-export-path-row">
+                <input
+                  id="db-export-path"
+                  className="db-export-path-input"
+                  value={destination.value}
+                  readOnly
+                  disabled={exporting}
+                  spellCheck={false}
+                  autoComplete="off"
+                />
+                <button
+                  type="button"
+                  className="db-export-path-pick"
+                  onClick={() => void destination.onPick(currentOptions)}
+                  disabled={exporting}
+                  aria-label="Choose export location"
+                  title="Choose export location"
+                >
+                  ...
+                </button>
+              </div>
+              {destination.hint && <span className="db-export-hint">{destination.hint}</span>}
+            </div>
+          )}
+
           {/* HTML style + bundle (HTML only) — also chip rows */}
           {showHtmlOptions && (
             <>

package/src/Export/ExportToolbarControls.tsx

@@ -7,7 +7,16 @@
  * Must be rendered inside <EditorProvider> so useEditorContext() works.
  */
 
-import { useState, useCallback, useEffect, useRef, useMemo, type ComponentType } from 'react';
+import {
+  lazy,
+  Suspense,
+  useState,
+  useCallback,
+  useEffect,
+  useRef,
+  useMemo,
+  type ComponentType,
+} from 'react';
 import { useEditorContext } from '@bendyline/squisq-editor-react';
 import { getThemeSummaries } from '@bendyline/squisq/schemas';
 import { parseMarkdown } from '@bendyline/squisq/markdown';
@@ -20,15 +29,53 @@ import {
   loadLastExportOptions,
   saveExportOptions,
 } from './export-options.js';
-import { ExportDialog } from './ExportDialog.js';
-import { runExport } from './run-export.js';
+import type { ExportBlobSaver } from './run-export.js';
 import { loadTransformStyleSummaries, type ExportSummaryOption } from './transform-summaries.js';
 
+const ExportDialog = lazy(() =>
+  import('./ExportDialog.js').then((module) => ({ default: module.ExportDialog })),
+);
+
+let runExportModulePromise: Promise<typeof import('./run-export.js')> | null = null;
+
+function loadRunExportModule(): Promise<typeof import('./run-export.js')> {
+  runExportModulePromise ??= import('./run-export.js');
+  return runExportModulePromise;
+}
+
 export interface ExportToolbarControlsProps {
   /** Currently selected file path — used to derive the download filename. */
   selectedFile: string | null;
   /** Media container for resolving images during export. */
   mediaContainer?: ContentContainer | null;
+  /** Override the default browser download behavior for host-provided save flows. */
+  saveBlob?: ExportBlobSaver;
+  /** Optional host adapter for displaying, picking, and saving to a native target path. */
+  destinationAdapter?: ExportDestinationAdapter;
+  /** Render the trigger as a direct Export button instead of the overflow menu. */
+  trigger?: 'menu' | 'button';
+  /** Whether to show video export in the overflow menu. */
+  showVideoExport?: boolean;
+}
+
+/** Host-specific operations behind the shared export destination control. */
+export interface ExportDestinationTarget {
+  grantId: string | null;
+  displayPath: string;
+}
+
+export interface ExportDestinationAdapter {
+  resolveTarget: (filename: string) => Promise<ExportDestinationTarget>;
+  pickTarget: (
+    filename: string,
+    currentTarget?: ExportDestinationTarget | null,
+  ) => Promise<ExportDestinationTarget | null>;
+  saveBlob: (
+    blob: Blob,
+    filename: string,
+    target?: ExportDestinationTarget | null,
+  ) => Promise<ExportDestinationTarget | null>;
+  hint?: string;
 }
 
 type ParsedMarkdown = ReturnType<typeof parseMarkdown>;
@@ -92,6 +139,10 @@ function quickLabel(opts: ExportOptions, transformSummaries: ExportSummaryOption
 export function ExportToolbarControls({
   selectedFile,
   mediaContainer,
+  saveBlob,
+  destinationAdapter,
+  trigger = 'menu',
+  showVideoExport = true,
 }: ExportToolbarControlsProps) {
   const { markdownSource, markdownDoc } = useEditorContext();
   const [menuOpen, setMenuOpen] = useState(false);
@@ -103,6 +154,8 @@ export function ExportToolbarControls({
   const [videoDoc, setVideoDoc] = useState<VideoExportModalProps['doc'] | null>(null);
   const [transformSummaries, setTransformSummaries] = useState<ExportSummaryOption[]>([]);
   const [exporting, setExporting] = useState(false);
+  const [destinationTarget, setDestinationTarget] = useState<ExportDestinationTarget | null>(null);
+  const destinationRequestRef = useRef(0);
   const menuRef = useRef<HTMLDivElement>(null);
 
   const lastOptions = loadLastExportOptions();
@@ -174,10 +227,30 @@ export function ExportToolbarControls({
     setMenuOpen((prev) => !prev);
   }, []);
 
+  const refreshDestination = useCallback(
+    async (options: ExportOptions) => {
+      if (!destinationAdapter) return;
+
+      const requestId = destinationRequestRef.current + 1;
+      destinationRequestRef.current = requestId;
+
+      try {
+        const { buildExportFilename } = await loadRunExportModule();
+        const filename = buildExportFilename(selectedFile, options);
+        const target = await destinationAdapter.resolveTarget(filename);
+        if (destinationRequestRef.current === requestId) setDestinationTarget(target);
+      } catch {
+        if (destinationRequestRef.current === requestId) setDestinationTarget(null);
+      }
+    },
+    [destinationAdapter, selectedFile],
+  );
+
   const handleOpenDialog = useCallback(() => {
     setMenuOpen(false);
     setDialogOpen(true);
-  }, []);
+    void refreshDestination(dialogInitial);
+  }, [dialogInitial, refreshDestination]);
 
   const handleCloseDialog = useCallback(() => {
     setDialogOpen(false);
@@ -206,17 +279,70 @@ export function ExportToolbarControls({
     setVideoLoadError(null);
   }, []);
 
+  const handleOptionsChange = useCallback(
+    (options: ExportOptions) => {
+      void refreshDestination(options);
+    },
+    [refreshDestination],
+  );
+
+  const handlePickDestination = useCallback(
+    async (options: ExportOptions) => {
+      if (!destinationAdapter) return;
+      try {
+        const { buildExportFilename } = await loadRunExportModule();
+        const filename = buildExportFilename(selectedFile, options);
+        const pickedTarget = await destinationAdapter.pickTarget(filename, destinationTarget);
+        if (pickedTarget === null) return;
+        setDestinationTarget(pickedTarget);
+      } catch {
+        // Native hosts surface picker failures through their own UI channel.
+      }
+    },
+    [destinationAdapter, destinationTarget, selectedFile],
+  );
+
+  const saveToDestination = useCallback(
+    async (blob: Blob, filename: string, target: ExportDestinationTarget | null) => {
+      if (!destinationAdapter) return;
+      const savedTarget = await destinationAdapter.saveBlob(blob, filename, target);
+      if (savedTarget) setDestinationTarget(savedTarget);
+    },
+    [destinationAdapter],
+  );
+
+  const handleDestinationSaveBlob = useCallback(
+    async (blob: Blob, filename: string) => {
+      await saveToDestination(blob, filename, destinationTarget);
+    },
+    [destinationTarget, saveToDestination],
+  );
+
   const handleExport = useCallback(
     async (opts: ExportOptions) => {
       setExporting(true);
       try {
-        await runExport(markdownSource, selectedFile, opts, mediaContainer);
+        const { runExport } = await loadRunExportModule();
+        await runExport(
+          markdownSource,
+          selectedFile,
+          opts,
+          mediaContainer,
+          destinationAdapter ? handleDestinationSaveBlob : saveBlob,
+        );
       } finally {
         setExporting(false);
         setDialogOpen(false);
       }
     },
-    [markdownSource, selectedFile, mediaContainer],
+    [
+      markdownSource,
+      selectedFile,
+      mediaContainer,
+      destinationAdapter,
+      handleDestinationSaveBlob,
+      saveBlob,
+    ],
   );
 
   const handleQuickExport = useCallback(async () => {
@@ -225,55 +351,108 @@ export function ExportToolbarControls({
     setExporting(true);
     try {
       saveExportOptions(lastOptions);
-      await runExport(markdownSource, selectedFile, lastOptions, mediaContainer);
+      const { runExport } = await loadRunExportModule();
+      let quickTarget: ExportDestinationTarget | null = null;
+      if (destinationAdapter) {
+        const { buildExportFilename } = await loadRunExportModule();
+        quickTarget = await destinationAdapter.resolveTarget(
+          buildExportFilename(selectedFile, lastOptions),
+        );
+      }
+      await runExport(
+        markdownSource,
+        selectedFile,
+        lastOptions,
+        mediaContainer,
+        destinationAdapter
+          ? async (blob, filename) => saveToDestination(blob, filename, quickTarget)
+          : saveBlob,
+      );
     } finally {
       setExporting(false);
     }
-  }, [lastOptions, markdownSource, selectedFile, mediaContainer]);
+  }, [
+    destinationAdapter,
+    lastOptions,
+    markdownSource,
+    mediaContainer,
+    saveBlob,
+    saveToDestination,
+    selectedFile,
+  ]);
 
   const LoadedVideoExportModal = videoModules?.Modal;
 
   return (
     <>
-      <div className="db-toolbar-menu" ref={menuRef}>
+      {trigger === 'button' ? (
         <button
-          className="db-toolbar-menu-trigger"
-          onClick={handleToggleMenu}
-          aria-label="More actions"
-          title="More actions"
+          type="button"
+          className="squisq-toolbar-button db-toolbar-export-trigger"
+          onClick={handleOpenDialog}
+          disabled={exporting}
+          aria-label="Export document"
+          data-tooltip={exporting ? 'Exporting...' : 'Export document'}
         >
-          &middot;&middot;&middot;
+          <ExportGlyph />
         </button>
+      ) : (
+        <div className="db-toolbar-menu" ref={menuRef}>
+          <button
+            className="db-toolbar-menu-trigger"
+            onClick={handleToggleMenu}
+            aria-label="More actions"
+            title="More actions"
+          >
+            &middot;&middot;&middot;
+          </button>
 
-        {menuOpen && (
-          <div className="db-toolbar-menu-dropdown">
-            {lastOptions && (
-              <button
-                className="db-toolbar-menu-item"
-                onClick={handleQuickExport}
-                disabled={exporting}
-              >
-                {quickLabel(lastOptions, transformSummaries)}
+          {menuOpen && (
+            <div className="db-toolbar-menu-dropdown">
+              {lastOptions && (
+                <button
+                  className="db-toolbar-menu-item"
+                  onClick={handleQuickExport}
+                  disabled={exporting}
+                >
+                  {quickLabel(lastOptions, transformSummaries)}
+                </button>
+              )}
+              <button className="db-toolbar-menu-item" onClick={handleOpenDialog}>
+                Export...
               </button>
-            )}
-            <button className="db-toolbar-menu-item" onClick={handleOpenDialog}>
-              Export...
-            </button>
-            <div className="db-toolbar-menu-divider" />
-            <button className="db-toolbar-menu-item" onClick={handleOpenVideoModal}>
-              Export Video...
-            </button>
-          </div>
-        )}
-      </div>
+              {showVideoExport && (
+                <>
+                  <div className="db-toolbar-menu-divider" />
+                  <button className="db-toolbar-menu-item" onClick={handleOpenVideoModal}>
+                    Export Video...
+                  </button>
+                </>
+              )}
+            </div>
+          )}
+        </div>
+      )}
 
       {dialogOpen && (
-        <ExportDialog
-          initial={dialogInitial}
-          exporting={exporting}
-          onExport={handleExport}
-          onClose={handleCloseDialog}
-        />
+        <Suspense fallback={null}>
+          <ExportDialog
+            initial={dialogInitial}
+            exporting={exporting}
+            destination={
+              destinationAdapter
+                ? {
+                    value: destinationTarget?.displayPath ?? '',
+                    onPick: handlePickDestination,
+                    hint: destinationAdapter.hint,
+                  }
+                : undefined
+            }
+            onExport={handleExport}
+            onOptionsChange={destinationAdapter ? handleOptionsChange : undefined}
+            onClose={handleCloseDialog}
+          />
+        </Suspense>
       )}
 
       {videoModalOpen && (videoLoading || videoLoadError) && (
@@ -311,3 +490,22 @@ export function ExportToolbarControls({
     </>
   );
 }
+
+function ExportGlyph() {
+  return (
+    <svg
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M4.5 1.75h4.25L12 5v7.25a1.5 1.5 0 0 1-1.5 1.5h-6A1.5 1.5 0 0 1 3 12.25v-9a1.5 1.5 0 0 1 1.5-1.5z" />
+      <path d="M8.75 1.75V5h3.25" />
+      <path d="M6 8.75h4.5" />
+      <path d="M8.75 7 10.5 8.75 8.75 10.5" />
+    </svg>
+  );
+}

package/src/Export/export-destination.ts

@@ -0,0 +1,30 @@
+/** Keep a user-edited target name while switching the selected export format. */
+export function updateExportTargetExtension(targetPath: string, suggestedFilename: string): string {
+  const nextExtension = extensionOf(suggestedFilename);
+  if (!nextExtension) return targetPath;
+  if (!targetPath.trim()) return suggestedFilename;
+
+  const suffixIndex = firstSuffixIndex(targetPath);
+  const pathPart = suffixIndex === -1 ? targetPath : targetPath.slice(0, suffixIndex);
+  const suffix = suffixIndex === -1 ? '' : targetPath.slice(suffixIndex);
+  const separatorIndex = Math.max(pathPart.lastIndexOf('/'), pathPart.lastIndexOf('\\'));
+  const dotIndex = pathPart.lastIndexOf('.');
+  const stem = dotIndex > separatorIndex ? pathPart.slice(0, dotIndex) : pathPart;
+  return `${stem}${nextExtension}${suffix}`;
+}
+
+function extensionOf(value: string): string {
+  const suffixIndex = firstSuffixIndex(value);
+  const pathPart = suffixIndex === -1 ? value : value.slice(0, suffixIndex);
+  const separatorIndex = Math.max(pathPart.lastIndexOf('/'), pathPart.lastIndexOf('\\'));
+  const dotIndex = pathPart.lastIndexOf('.');
+  return dotIndex > separatorIndex ? pathPart.slice(dotIndex) : '';
+}
+
+function firstSuffixIndex(value: string): number {
+  const query = value.indexOf('?');
+  const fragment = value.indexOf('#');
+  if (query === -1) return fragment;
+  if (fragment === -1) return query;
+  return Math.min(query, fragment);
+}